> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/api-reference/card-registrations/card-registration-object/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.
# The Card Registration object
> Register card details to obtain a `CardId` token for one-time, recurring, or preauthorized card payments
### Description
Mangopay relies on the Card Registration object to safely tokenize a card and create the [Card](/api-reference/cards/card-object) object.
Successfully registering a card to create the Card object is a multiple-step process. It is necessary to process card payments (direct, preauthorized, and recurring card pay-ins) or validate the card.
> **Note**
>
> **Note – Card validation within 24 hours**
>
> A successful transaction (preauthorization, pay-in, or recurring) or card validation within 24 hours of the card registration is required to validate a card. Otherwise, the card becomes invalid and a new card registration will be necessary.
> **Warning**
>
> **Warning – End user approval**
>
> Under no circumstances should card information be kept without the end user's approval. If you don’t have the end user’s approval, you need to deactivate the card.
> **Check**
>
> **Best practice – Use Checkout SDK**
>
> Simplify payments by card and other payment methods with the Mangopay [Checkout SDK](/sdks/checkout).
### Attributes
### Schema (`CardRegistrationResponse`)
```yaml
components:
schemas:
Tag_CardRegistration:
type: string
description: >-
Max. length: 255 characters
Custom data that you can add to this object, such as unique identifiers
in your system. To store multiple values, you can serialize them into a
single string, for example a JSON object:
`"{\"id_1\":AB123,\"id_2\":DE456}"`.
This value will also be inherited by the Card object's `Tag` parameter
and cannot be edited.
title: Tag_CardRegistration
CreationDate:
type: integer
description: Unix timestamp (UTC) of the date and time the object was created.
title: CreationDate
ResultCode:
type: string
description: >-
The code indicating the result of the operation. This information is
mostly used to handle errors or for
filtering purposes.
title: ResultCode
ResultMessage:
type: string
description: The explanation of the result code.
title: ResultMessage
CardRegistrationResponse:
type: object
properties:
Id:
type: string
description: The unique identifier of the Card Registration object.
Tag:
$ref: '#/components/schemas/Tag_CardRegistration'
CreationDate:
$ref: '#/components/schemas/CreationDate'
UserId:
type: string
description: The unique identifier of the user the card belongs to.
AccessKey:
type: string
description: >-
The secure value to use when tokenizing the card via the dedicated
endpoint.
PreregistrationData:
type: string
description: >-
The secure value to identify the registration when tokenizing the
card via the dedicated endpoint.
RegistrationData:
type: string
description: >-
The string returned by the tokenization server, which must be sent
in full as the `RegistrationData` on the PUT
Update a Card Registration endpoint to create the Card object.
CardId:
type: string
description: >-
The unique identifier of the Card object, which is returned after
updating the Card Registration object with the `RegistrationData`.
CardType:
type: string
description: >-
**Returned values:** `CB_VISA_MASTERCARD`, `AMEX`, `MAESTRO`, `BCMC`
**Default value:** `CB_VISA_MASTERCARD`
The type of the card. If not supplied, the default value will be
taken into account.
CardRegistrationURL:
type: string
description: >-
The URL to make the card tokenization call.
**Caution:** This variable URL is specific to each card
registration. You must rely on the returned URL in full (host, path,
and queries) and not hardcode any part of it.
ResultCode:
$ref: '#/components/schemas/ResultCode'
ResultMessage:
$ref: '#/components/schemas/ResultMessage'
Currency:
type: string
description: >-
**Returned values:** The three-letter ISO 4217
code (EUR, GBP, etc.) of a supported currency (depends on feature,
contract, and activation settings).
The currency of the card.
Status:
type: string
description: >-
**Returned values:** `CREATED`, `VALIDATED`, `ERROR`
The status of the card registration:
- `CREATED` – The card registration has been created, but no
`RegistrationData` has been entered yet and the `CardId` value is
`null`.
- `VALIDATED` – The card registration has been successfully updated
with the `RegistrationData` from the tokenization server.
- `ERROR` – The card registration couldn't be updated with the
`RegistrationData` and no `CardId` was generated. For more
information, refer to the `ResultCode` (105206, 105299) and `ResultMessage`.
title: CardRegistrationResponse
```
> Register card details to obtain a `CardId` token for one-time, recurring, or preauthorized card payments