Activate card for customer

post

https://sandcaas.undostres.com.mx/debit/v1/activateCardForCustomer

After receiving their card, the cardholder is to call this endpoint to register an account in UnDosTres and activate the card.

Also, you can activate several cards for the same account in case o enterprise users creation. This endpoint supports two modes of operation:

If customer_id is provided in the request body, it will associate the new card with the existing customer.
If customer object is provided instead, a new customer will be created using that information and the card will be linked to it.

Accounts with a Composite Balance can also use this endpoint to register and activate their accounts. You can learn more about these accounts here: Composite Balance

Example 1: Only `customer_id` provided

{
    "customer_id": "12345678",
    "card_identifier": "CARD-001",
    "reference_batch": "7e4b85e27c4610824900af48f340394d"
}

Example 2: Only `customer` object provided

{
    "customer": {
        "first_name": "Laura",
        "last_name": "Pérez",
        "email": "[email protected]",
        "phone_number": "+5215512345678"
    },
    "card_identifier": "CARD-001",
    "reference_batch": "7e4b85e27c4610824900af48f340394d"
}

Example 3: Both `customer_id` and `customer` (customer_id takes precedence)

{
    "customer_id": "12345678",
    "customer": {
        "first_name": "Ignorado",
        "last_name": "También",
        "email": "[email protected]",
        "phone_number": "+5215511111111"
    },
    "card_identifier": "CARD-001",
    "reference_batch": "7e4b85e27c4610824900af48f340394d"
}

Example 4: When using Composite Balance (only for Credit Engine).

Just in case of a Composite Balance, a param balance is required. It will be an object with the id of the balance:

{
    "pin": "1234",
    "card_identifier": "CARD001",
    "reference_batch": "7e4b85e27c4610824900af48f340394d",
    "device_id": "2fc54683d5fad405360419f720457ccbcf9bacac414f6296f846e2e4fad99d47",
    "customer_id": "85",
    "balance": {
        "id": 10249
    }
}

Successful response (applies to all cases)

{
    "text": "Success",
    "timestamp": "2024-11-15T14:32:18.123Z",
    "endpoint": "debit/v1/activateCardForCustomer",
    "error": {},
    "payload": {
        "card_id": "card_987654321",
        "customer_id": "12345678",
        "status": "activated"
    }
}

Here some error responses, for instance:

Note: Empty error in successful requests

{
    "text": "Error",
    "timestamp": "2025-11-18T11:50:57.960232171-06:00",
    "endpoint": "/debit/v1/activateCardForCustomer",
    "error": {
        "code": 7000,
        "text": "Server error",
        "hints": [
            "Please contact the customer care",
            "rfc:invalid"
        ]
    }
}

The following are listed errors that may be occurring due to incorrect data being sent or any other problems that may arise.

Error with the reference batch. A reference batch does not exist.

"error": {
    "code": 4400,
    "hints": [
        "Bad parameters request, please refer the documentation",
        "Mismatch in reference batch."
    ]
}

Error with card identifier. A card identifier does not exist.

"error": {
    "code": 4400,
    "hints": [
        "Bad parameters request, please refer the documentation",
        "Mismatch in card batch."
    ]
}

Error in communication with the card service provider.

"error": {
    "code": 5001,
    "text": "Wrong parameters"
}

Invalid RFC for the data submitted or existing in the customer list.

"error": {
    "code": 7000,
    "text": "Server error",
    "hints": [
        "Please contact the customer care",
        "rfc:invalid"
    ]
}

Invalid email.

"error": {
    "code": 4400,
    "hints": [
        "Customer whith this email is already created"
    ]
}

First name.

"error": {
    "code": 4400,
    "hints": [
        "Customer first name is required and can't be empty"
    ]
}

For a single physical card, and it is already activated for the user.

"error": {
    "code": 4400,
    "hints": [
        "This customer already have a physical card"
    ]
}

Lastname.

"error": {
    "code": 4400,
    "hints": [
        "Customer first name is required and can't be empty"
    ]
}

Empty reference batch.

"error": {
    "code": 4400,
    "hints": [
        "Reference batch can't be empty"
    ]
}

Empty card identifier.

"error": {
    "code": 4400,
    "hints": [
        "Card identifier can't be empty"
    ]
}

There is no card for that card identifier.

"error": {
    "code": 4400,
    "hints": [
        "Missing card to provided batch reference and card identifier"
    ]
}

PIN validations.

"error": {
    "code": 4400,
    "hints": [
        "Invalid pin. Pin should have only digits"
    ]
}

"error": {
    "code": 4400,
    "hints": [
        "Invalid pin. Pin should have 4 digits"
    ]
}

Card already activated.

"error": {
    "code": 4433,
    "hints": [
        "Card has already been activated"
    ]
}