NAV
json

Introduction

Welcome to the NeCIPCo! You can use our API to access Nueve09 Card Issuing API endpoints, which can help you to manage your cards from your card program.

We have json example calls! You can view code examples in the dark area to the right, and you can copy the example json.

Base URL

All the request use a Base URL with the following pattern https://address/version/resources, the current version is V1 and there are 2 deployed environments TEST and PRODUCTION:

Data encryption & Encoding

Encryption

In NeCIPCo, all the sensitive information is exchanged ciphered using RSA Public/Private Pair Keys.

The sended sensitive data (like 16 digit card numbers & pins), must be always encrypted in every request with system public key returned in Get Public Key.

The received sensitive data (like 16 digit card numbers & pins), is always returned encrypted in every response with the api client public key registered in Add Public Key, and must be decrypted with your Private key file.

You can generate a RSA Key pair for encrypt/decrypt information using OpenSSL with the following commands (GNU/Linux or MacOS shells):

  1. Generate a 2048 bit RSA
    1. With password
      • $ openssl genrsa -des3 -out private.pem 2048
    2. Without password
      • $ openssl genrsa -out private.pem 2048
  2. Export the RSA Public Key to a File (the -pubout flag is really important.)
    • $ openssl rsa -in private.pem -outform PEM -pubout -out public.pem
  3. Verify the exported RSA Public Key (starts with -----BEGIN PUBLIC KEY-----)
    • $ cat public.pem
  4. If you need too export your private key (EXTREMELY DANGEROUS!) use the following command:
    • $ openssl rsa -in private.pem -out private_unencrypted.pem -outform PEM

  5. Verify the exported RSA Private Key (starts with -----BEGIN RSA PRIVATE KEY-----)
    • $ cat private_unencrypted.pem

Encoding

If you need to make a POST, PUT request and send data in body params, the sensitive information after encrypted, must be encoded in Base 64 (RFC 4648) before to be sended.

If you need to make a GET request and send data in query params, the sensitive information after encrypted, must be encoded in Base 64 Encoded with URL and Filename Safe Alphabet (RFC 4648) before to be sended. In general, you need to use '-' instead of '+' and '_' instead of '/'. Note that the result can still contain '=' as padding character and must be avoided in the final encoding result.

Authentication

CiMAPI uses API keys and password to allow access to the API. You can request an user & password combination in .

The client starts authentication using the POST /auth/login service see Get authorization Token. If the authentication succeeds, a JWT token is dispatched to the client in the Authorization response header, with format Bearer #{token}.

The client can use this token to authenticate following requests for the same user, providing it in the Authorization request header, also with format Bearer #{token}

The Bearer #{token} is expected for CiMAPI in all the API calls (except in login), the header looks like the following:

Authorization: Bearer ey61tqga7aYQk1I1NiJ9.ksiwtags&qIyMDNmMDQxha729smdhsQwODgtOTlmOS00NzdkNTI1ZTNkZGIiLCJzdWIiOiIxNjE1NDlkNS02NDRiLTRkZjItYmZjOC00YjNkZjJlNmEzMjciLCJzY3AiOioajqtw536qYU1q(iwiYXVkIjpudWxsLCJpYXQiOjE2MDc5NzU0NTgsImV4cCI6MTYwODA2MTg1OH0.9q5taGtw2-0Op1KDqizDKBSRE3Id7dAappWuDb0BaP0

Get authorization token

Example JSON Request:

 {
     "api_client": {
         "api_key": "api_key", 
         "password": "password"
     }
 }

Example JSON Response:

{
    "status": {
        "code": 200,
        "message": "Logged in successfully."
    },
    "data": {
        "client": {
            "id": "3c971526-6abd-42d8-8532-647c986ab493",
            "name": "Nueve09",
            "alias": "NUEVE09",
            "code": "NUE",
            "entity_code": "123",
            "email": "[email protected]",
            "available": 22814.55,
            "balance": 1154.0,
            "timezone": "America/Mexico_City",
            "status": "ACTIVE",
            "created_at": "2020-11-04T19:36:04.399-06:00",
            "updated_at": "2020-12-14T13:55:50.246-06:00"
        }
    }
}

This endpoint retrieves an Authorization Bearer token and api_client basic information. The authorization token is returned in headers as "Authorization"

HTTP Request

POST /auth/login

Header Parameters

Header Description
Content-Type application/json

Body Parameters

Parameter Description
api_client.api_key
required		 The api_key assignated to your user.
api_client.password
required		 The password assignated for authentication.

Expire authorization token

Example JSON Request:

DELETE /auth/logout

Example JSON Response:

{}

This endpoint revoke an Authorization Bearer token created by Get authorization Token.

HTTP Request

DELETE /auth/logout

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Cardholder

Get a cardholder

Example JSON Request:

GET /cardholders?id=ec123456-1qq2-1234-tt5g-8873fe52bf54

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "cardholder": {
            "id": "ec123456-1qq2-1234-tt5g-8873fe52bf54",
            "first_name": "John",
            "second_name": "Doe",
            "surname": "González",
            "second_surname": "Pérez",
            "rfc": "XAXX010101000",
            "curp": "XEXX010101HNEXXXA4",
            "email": "[email protected]",
            "primary_phone": "5555555555",
            "mobile_phone": "5555555555",
            "address": {
                "street": "Av. Siempre",
                "external_street_number": "#12",
                "internal_street_number": "Lt3.",
                "suburb": "Nápoles",
                "township": "Benito Juárez",
                "city": "Ciudad de México",
                "state": "CDMX",
                "postal_code": "55120",
                "country": "484"
            },
            "birthdate": "1995-09-22",
            "gender": "M",
            "gross_monthly_income": 20000,
            "net_monthly_income": 20000,
            "observations": "",
            "has_kids": true,
            "marital_status": "CASADO",
            "external_id": "123",
            "accounts": [
                {
                    "id": "cca4c4a5-504e-4fa4-bafc-a947bcf77f4e",
                    "account_number": 555555555,
                    "creation_date": "2020-11-25T18:00:00.000-06:00",
                    "activation_date": null,
                    "assigned_by": "161549d5-644b-4df2-bfc8-4b3df2e6a327",
                    "status": "ACTIVE",
                    "document": {
                        "type": "INE",
                        "number": "321321321321321"
                    },
                    "cards": [
                        {
                            "id": "12123214-2e34-4fff-844f-321654987123",
                            "last_four": "1234",
                            "assignation_date": "2020-11-26T02:26:32.066-06:00",
                            "status": "ACTIVE",
                            "assigned_by": {
                                "id": "161549d5-644b-4df2-bfc8-4b3df2e6a327",
                                "alias": "API_KEY",
                                "name": "WS_NAME",
                                "description": ""
                            }
                        }
                    ]
                }
            ]
        }     
    }
}

This operation query a cardholder using several param filters. If several params are used to search, they will be concatenated with AND operator. At least one param filter should be specified.

HTTP Request

GET /cardholders

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Query Parameters

Parameter Type Pattern Description
id
optional		 string uuid The card_id to search.
rfc
optional		 string 10-13 characters The rfc to search.
curp
optional		 string 18 characters The curp to search.
email
optional		 string 5-100 characters The email to search.
primary_phone
optional		 string 10 digits The primary_phone to search.
mobile_phone
optional		 string 10 digits The mobile to search.

Create a cardholder

Example JSON Request:

{
    "first_name": "John",
    "second_name": "Doe",
    "surname": "González",
    "second_surname": "Pérez",
    "rfc": "XAXX010101000",
    "curp": "XEXX010101HNEXXXA4",
    "email": "[email protected]", 
    "primary_phone": "5555555555",
    "mobile_phone": "5555555555",
    "street": "Av. Siempre",
    "ext_street_number": "#12",
    "int_street_number": "Lt3.",
    "suburb": "Nápoles",
    "township": "Benito Juárez",
    "city": "CDMX",
    "state": "CDMX",
    "postal_code": "55120",
    "birthdate": "1995-09-22", 
    "gender": "MALE",
    "marital_status": "SOLTERO",
    "has_kids": false,
    "gross_monthly_income": 20000,
    "net_monthly_income": 18000,
    "observations": ""
}

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "cardholder": {
            "id": "ec123456-1qq2-1234-tt5g-8873fe52bf54",
            "first_name": "John",
            "second_name": "Doe",
            "surname": "González",
            "second_surname": "Pérez",
            "rfc": "XAXX010101000",
            "curp": "XEXX010101HNEXXXA4",
            "email": "[email protected]"
        }
    }
}

This endpoint creates a cardholder.

HTTP Request

POST /cardholders

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
first_name
required		 string 1-12 characters The cardholder's first name.
second_name
required		 string 1-12 characters The cardholder's second name.
surname
required		 string 1-12 characters The cardholder's surname.
second_surname
required		 string 1-12 characters The cardholder's second surname.
rfc
required		 string 10-13 characters The cardholder's RFC.
curp
required		 string 18 characters The cardholder's CURP.
email
required		 string email The cardholder's email.
primary_phone
required		 string 10 digits The cardholder's primary phone. Can be local phone or mobile_phone.
mobile_phone
required		 string 10 digits The cardholder's mobile_phone.
street
required		 string 1-20 characters The cardholder's street address.
ext_street_number
required		 string 1-5 characters The cardholder's street address number.
int_street_number
optional		 string 1-5 characters The cardholder's street address number.
suburb
required		 string 1-25 characters The cardholder's suburb address.
city
required		 string 1-25 characters The cardholder's city address.
state
required		 string States The cardholder's state address. See allowed values in Get States Catalog
postal_code
required		 string 5 digits The cardholder's address postal code.
birthdate
required		 date YYYY-MM-dd The cardholder's birthdate.
gender
required		 string Gerequirednder The cardholder's gender. See allowed values in Get Gender Catalog
marital_status
required		 string Marital Status The cardholder's marital status. See allowed values in Get Marital Status Catalog
has_kids
required		 boolean true or false If cardholder's has kids or not.
gross_monthly_income
optional		 float digits Cardholder's gross monthly income (in MXN).
net_monthly_income
optional		 float digits Cardholder's net monthly income (in MXN).
observations
optional		 string 0-100 characters Some observations about cardholder.
external_id
optional		 string 0-40 characters A place to put an external reference. If provided, it must be unique.

Cards

Assign a card to a cardholder

Example JSON Request:

{
    "card_number":"t7wog3ytUChBC2xdLNe-sAQ-VXt7xgDi6U_iNSGQPyA7hPBYs1-_mLt", 
    "cardholder_id": "55555555-daa7-1234-aaaa-123123123ecd",
    "document_type": "INE",
    "document_number": "1234123412",
    "observations":"",
    "latitude": 12.65343,
    "longitude": -134.87536
}

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "cardholder": {
            "id": "ab123456-1qq2-1234-tt5g-8873fe52bf54" ,
            "first_name": "John",
            "second_name": "Doe",
            "surname": "González",
            "second_surname": "Pérez",
            "rfc": "XAXX010101000",
            "curp": "XEXX010101HNEXXXA4"
        },
        "card": {
            "id": "11111111-daa7-1234-aaaa-123123123ecd",
            "type": "PHISYCAL",
            "status": "NEED_ACTIVATION",
            "masked_card_number": "************1234",
            "card_number": "************1234"       
        },
        "account": {
            "id": "22222222-daa7-1234-aaaa-123123123ecd",
            "reference": "555555555",
            "clabe": null
        }
    }
}

This operations allow you to assign a card from the stock to a cardholder.

HTTP Request

PUT /cards

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* The card_number to be assigned
cardholder_id
required		 string uuid The cardholder's id.
document_type
required		 string Document Type The cardholder's document type to be registeres with the card. See allowed values in Get Document Type Catalog
document_number
required		 string 1-27 characters The document number belonging to the document type
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the assignment is made. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the assignment is made. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180
observations
optional		 string 0-100 characters Some comment about the assignation

Activate a card

Example JSON Request:

{
    "card_number": "11111111-daa7-1234-aaaa-123123123ecd",
    "latitude": 12.12345,
    "longitude": 15.12345
}

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "card": {
            "id": "11111111-daa7-1234-aaaa-123123123ecd",
            "masked_card_number": "************1234", 
            "type": "PHYSICAL",
            "status": "ACTIVE"        
        },
        "account": {
             "id": "12312312-1234-1234-1234-123456123123",
             "reference": "555555555"
        }
    }
}

This operation allow you to activate a card. Every card in stock is created in a "Non Active status" (NEED_ACTIVATION), and you need to activate each card explicity.

HTTP Request

POST /cards/activate

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid The card_number or card_id to be activated.
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the activation is made. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the activation is made. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180

Change card status

Example JSON Request:

{
    "card_number": "11111111-daa7-1234-aaaa-123123123ecd",
    "status": "TEMPORARY_INACTIVE",
    "latitude": 12.12345,
    "longitude": 15.12345
}

Example JSON Response:


{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
       "card": {
            "id": "11111111-daa7-1234-aaaa-123123123ecd",
            "masked_card_number": "************1234", 
            "type": "PHYSICAL",
            "status": "TEMPORARY_INACTIVE"        
        },
        "account": {
             "id": "12312312-1234-1234-1234-123456123123",
             "reference": "555555555"
        }
    }
}

This operation allow you to change the card status. You can block/unblock a card to accept or deny transactions, report for a replacement or make preventive blocks for the card.

HTTP Request

PUT /cards/status

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid The card_number or card_id to be updated.
status
required		 string Catalog The update status for the card. See allowed values in Get Card Status Catalog
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the status update is made. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the status update is made. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180

Get the card balance

Example JSON Request:

GET /cards/balance?card_number=11111111-daa7-1234-aaaa-123123123ecd&movements=true

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "available": 500,
        "card": {
            "id": "11111111-daa7-1234-aaaa-123123123ecd",
            "masked_card_number": "************1234", 
            "type": "PHYSICAL",
            "status": "ACTIVE"        
        },
        "account": {
             "id": "12312312-1234-1234-1234-123456123123",
             "reference": "555555555"
        },
        "movements": [ {
                          "fecha": "20201214",
                          "hora": "195550",
                          "comercio": "FINPULSO SAPI",
                          "importe": "350.11",
                          "descripcion_importe": null,
                          "codigo_autorizacion": "504884"
                       }
        ]
    }
}

This operations allow you to query a card balance and recent transactions information.

HTTP Request

GET /cards/balance

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Query Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid The card_number or card_id to be requested.
movements
required		 boolean true or false Set if you want the last movements.

Get card info

Example JSON Request:

GET /cards/info?card_number=11111111-daa7-1234-aaaa-123123123ecd

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "account": {
            "id": "78458a5b-ac25-4f7a-1234-4cb78eeb234e",
            "reference": 555555555
        },
        "card": {
            "id": "11111111-daa7-1234-aaaa-123123123ecd",
            "masked_card_number": "************1234",
            "card_type": "PHYSICAL",
            "status": "ACTIVE",
            "card_number": "hsy36Gsrw934jhGUo/PMs8/dYFY+QBZidvVprSGXEZxo0Hk5HPVt3kEqI8dVvRlL8t8o0h6p5OwYnXx0Hg40E/btpkpbesKDqRjaTCPHs2Czi42Q7l1QJVCM4x5wBK18HByk3IMaGmzzCM4A1l3bF9eX/mZyaSdY3cpBdD3c2wRIX73Qju52btNqWY6PIVVAI1VnocHGWBYDxHWDjL/pbx1H+iD3wlDPoezpEQk4d7IkXWyueDoyU2PAOZd7EC4Zs+uFMtiNCQUOXCbBtKgCAsAPy18UzN54i2Lv+0Y1EOQ6GM0xoqHersqPPrZ/6EBYD1ki9AsCKi7H5eDTN4oLqg==",
            "activity": {
                "last_approved_operation": "N/D",
                "last_denied_operation": "2021-04-08 15:54:37",
                "last_block_status": "2021-04-05 22:57:15"
            }        
        },
        "cardholder": {
            "name": "Jonh Doe",
            "phone": "5555555555",
            "address": "Av. Siempre #12 Lt3.",
            "postal_code": "55120",
            "township": "Benito Juárez",
            "country": "MEXICO                        ",
            "document": {
                "type": "INE",
                "number": "321321321321321"
            }
        }
    }
}

This operation allow you to query card user information.

HTTP Request

GET /cards/info

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Query Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid The card_number or card_id to be requested.

Authenticate card for cardholder

Example JSON Request:

GET /cards/authenticate?card_number=12123214-2e34-4fff-844f-321654987123&authentication_info=123476

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "Authentication successful!",
    "data": {
        "validated": true
    }
}

This endpoint allows you to authenticate a cardholder for card validation using the last 4 digits from the card number and 2 last digits from ATM PIN.

HTTP Request

GET /cards/authenticate

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Query Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid The card_number or card_id to be requested.
authentication_info
required		 string 6 digits Last four from card + 2 last ATM PIN digits

Get card PIN for POS

Example JSON Request:

GET /cards/pin/pos?card_number=11111111-daa7-1234-aaaa-123123123ecd&latitude=12.12345&longitude=-15.12345
{}

Example JSON Response:

 {
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "card": {
            "id": "11111111-daa7-1234-aaaa-123123123ecd",
            "masked_card_number": "************1234",
            "type": "PHYSICAL",
            "status": "ACTIVE",
            "pin": "krgwsrwsear4ggweg4sad8g45we4g5w4srd545a4g5rs4d7ghasdv4a5r4gasgasrhy8f7ju4k85448hg4n84f84b8fg4b8f4gb8dfgb4dfgb8d"        
        },
        "account": {
            "id": "78458a5b-ac25-4f7a-1234-4cb78eeb234e",
            "reference": 555555555
        }
    }
}

This operation allow you to query the PIN for POS purchases. This is the PIN used in transactions and purchases confirmation.

HTTP Request

GET /cards/pin/pos

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Query Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid The card_number or card_id to be requested.
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the pin is requestes. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the pin is requested. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180

Set ATM PIN

Example JSON Request:

{
    "card_number": "11111111-daa7-1234-aaaa-123123123ecd",
    "pin":"t7wog3ytUChBC2xdLNe-sAQ-VXt7xgDi6U_iNSGQPyA7hPBYs1-_mLtKKrF6yupZO8ZJwC2O-lehzCYeQ4tUQkebdCs",
    "latitude": 12.12345,
    "longitude": 15.12345
}

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "operation":{
            "id": "ab123456-1qq2-1234-tt5g-8873fe52bf54"
        },
        "card": {
            "id": "11111111-daa7-1234-aaaa-123123123ecd",
            "masked_card_number": "************1234",
            "type": "PHYSICAL",
            "status": "ACTIVE"      
        },
        "account": {
            "id": "78458a5b-ac25-4f7a-1234-4cb78eeb234e",
            "reference": 555555555
        }
    }
}

This operation allow you to set the ATM PIN. This PIN is used to withdraw cash in ATM machines. The use of this operation rewrites the PIN with the new a one without the knowlenge of the previous PIN. Can be used to clear the old pin and can bethe same as POS PIN but this is not required.

HTTP Request

POST /cards/pin

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid The card_number or card_id to be updated.
pin
required		 string 4 digits** The ATM PIN to be set.
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the set pin is requested. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the set pin is requested. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180

Update ATM PIN

Example JSON Request:

{
    "card_number": "11111111-daa7-1234-aaaa-123123123ecd",
    "old_pin": "z3S01qUrzJd7ZoiTkegq4JWCoB-NP2qgxQzSnklalnTSEPPbPEhyR_y3zTup6ZTQto0FXE1ArtLPmntQ6-RKg",
    "new_pin": "t7wog3ytUChBC2xdLNe-sAQ-VXt7xgDi6U_iNSGQPyA7hPBYs1-_mLtKKrF6yupZO8ZJwC2O-lehzCYeQ4tUQs",
    "latitude": 12.12345,
    "longitude": 15.12345
}

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "operation": {
           "id": "ab123456-1qq2-1234-tt5g-8873fe52bf54"
        },
        "card": {
          "id": "11111111-daa7-1234-aaaa-123123123ecd",
          "masked_card_number": "************1234",
          "type": "PHYSICAL",
          "status": "ACTIVE"
        },
        "account": {
          "id": "78458a5b-ac25-4f7a-1234-4cb78eeb234e",
          "reference": 555555555
        }
    }
}

This operation allow you to update the old ATM PIN with a new one. This service necessarily needs the correct old PIN to work.

HTTP Request

PUT /cards/pin

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid The card_number or card_id to be updated.
old_pin
required		 string 4 digits** The ATM PIN to be replaced.
new_pin
required		 string 4 digits** The new ATM PIN to be set.
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the pin update is requested. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the pin update is requested. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180

Validate ATM PIN

Example JSON Request:

GET /cards/pin/validate?card_number=12123214-2e34-4fff-844f-321654987123&latitude=12.12345&longitude=-5.12345&pin=t7wog3ytUChBC2xdLNe-sAQ-VXt7xgDi6U_iNSGQPyA7hPBYs1-_mLtKKrF6yupZO8ZJwC2O-lehzCYeQ4t

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "PIN Validated",
    "data": {
        "validated": true
    }
}

This operation allow you to validate an ATM PIN for a card. This operation is useful if yoy want to make a validation (user, transaction, etc...). If there is more than 5 wrong attemps, the service is going to be blocked temporaly, increasing the blocking time each 5 wrong attemps.

HTTP Request

GET /cards/pin/validate

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Query Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid The card_number or card_id to be validated.
pin
required		 string 4 digits** The ATM PIN to be validated.
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the validation is made. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the validation is made. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180

Make a transfer between cards

Example JSON Request:

{
    "origin_card": "11111111-daa7-1234-aaaa-123123123ecd",
    "destination_card": "v7ut6AztPIH_SJK9gRETQQnFmqFPS-qcexyuRly0Hr9_jaG5YAnE_7CNNl_nbLYBi6YJvpnoZFSQdVgPaSEPPbPEhyR_y3zTup6ZTQto0FXE1ArtLPmntQ6-RKg",
    "amount": 1000,
    "latitude": 12.12345,
    "longitude": 15.12345
}

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "operation": { 
            "id": "a5030ec4-1f66-445d-b4d2-e3cf3a055fc1",
            "authorization_code": 65498745,
            "amount": 1000
        },
        "origin_card": {
            "id": "11111111-daa7-1234-aaaa-123123123ecd",
            "account_id": "22222222-daa7-1234-aaaa-123123123ecd",
            "type": "PHYSICAL",
            "card_number": "************1234",
            "account_reference": 555555555,
            "previous_balance": 3000,
            "new_balance": 2000
        },
        "destination_card": {
            "id": "33333333-daa7-1234-aaaa-123123123ecd",
            "account_id": "44444444-daa7-1234-aaaa-123123123ecd",
            "card_number": "************4321",
            "previous_balance": 1000,
            "new_balance": 2000
        }
    }
}

This operations allow you to make a transfer C2C (Card to Card) between the BIN ecosystem cards.

HTTP Request

POST /cards/transfer

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
origin_card
required		 string 16 digits* or uuid The card_number or card_id to be requested.
destination_card
required		 string 16 digits* The card_number or card_id to be requested.
amount
required		 float digits Amount to transfer between cards
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the transfer is made. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the transfer is made. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180

Make a card disbursement

Example JSON Request:

{
    "card_number": "11111111-daa7-1234-aaaa-123123123ecd",
    "amount": 10000.00,
    "latitude": 12.12345,
    "longitude": 15.12345
}

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "operation": {
            "id": "4158d533-e95a-4c05-a341-ef7d369d3a09",
            "authorization_code": "542010",
            "amount": 10000.00
        },
        "card": {
            "id": "11111111-daa7-1234-aaaa-123123123ecd",
            "masked_card_number": "************1234",
            "type": "PHYSICAL",
            "status": "ACTIVE"      
        },
        "account": {
            "id": "22222222-daa7-1234-aaaa-123123123ecd",
            "reference": 555555555
        }
    }
}

This operation allow you to apply a disburse to a card in order to allow increase it's available balance to make transactions (purchases, withdrawals or transferences) and decreases your main balance available.

HTTP Request

POST /cards/disbursement

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid The card_number or card_id that will receive the disbursement
amount
required		 float digits The amount to disburse
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the disbursement is made. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the disbursement is made. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180

Make a payment to a card

Example JSON Request:

{
    "card_number": "11111111-daa7-1234-aaaa-123123123ecd",
    "amount": 1000.00,
    "payment_description": "ABONO POR COMISIONES",
    "latitude": 12.12345,
    "longitude": -15.12345
}

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "operation": {
            "id": "4158d533-e95a-4c05-a341-ef7d369d3a09",
            "authorization_code": "542010",
            "amount": 1000.00,
            "payment_description": "ABONO POR COMISIONES"
        },
        "card": {
            "id": "11111111-daa7-1234-aaaa-123123123ecd",
            "masked_card_number": "************1234",
            "type": "PHYSICAL",
            "status": "ACTIVE"      
        },
        "account": {
            "id": "22222222-daa7-1234-aaaa-123123123ecd",
            "reference": 555555555
        }
    }
}

This operation allow you to make a payment to a card. The payment is similar to Disburse, but allow you to specify a description for the payment. This operation increase your card's available balance and decreases your main balance available.

HTTP Request

POST /cards/payment

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid The card_number or card_id that will receive the payment
amount
required		 float digits The amount to receive has pay
payment_description
required		 string 1-32 characters The payment description
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the payment is made. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the payment is made. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180

Make a card withdrawal

Example JSON Request:

{
    "card_number": "11111111-daa7-1234-aaaa-123123123ecd",
    "amount": 1000.00,
    "pin": "t7wog3ytUb4pDQZT6AhE1USJab_-v7ut6AztPIH_SJK9gRETQQnFmqFPS-qcexyuRly0Hr9_jaG5YAnE_7CNNl_nbLYBi6YJvpnoZFSQdVgPaI0Pm07pl6SNPz3S0",
    "latitude": 12.12345,
    "longitude": -15.12345
}

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "operation": {
            "id": "4158d533-e95a-4c05-a341-ef7d369d3a09",
            "authorization_code": "542010",
            "amount": 1000.00
        },
        "card": {
            "id": "11111111-daa7-1234-aaaa-123123123ecd",
            "masked_card_number": "************1234",
            "type": "PHYSICAL",
            "status": "ACTIVE"      
        },
        "account": {
            "id": "22222222-daa7-1234-aaaa-123123123ecd",
            "reference": 555555555
        }
    }
}

This operation allow you to apply a withdrawal from a card. This operation decrease the available balance in card and increases your collection balance account.

HTTP Request

POST /cards/withdrawal

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid The card_number or card_id that will receive the withdrawal.
amount
required		 float digits The amount to withdraw
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the withdrawal is made. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the withdrawal is made. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180
pin
optional		 string 4 digits** The PIN if you need cardholder validation

Apply a purchase to a card

Example JSON Request:

{
    "card_number": "11111111-daa7-1234-aaaa-123123123ecd",
    "amount": 1000.55,
    "merchant_description": "CARGO POR COMISIONES",
    "pin":  "t7wog3ytUb4pDQZT6AhE1USJab_-v7ut6AztPIH_SJK9gRETQQnFmqFPS-qcexyuRly0Hr9_jaG5YAnE_7CNNl_nbLYBi6YJvpnoZFSQdVgPaI0Pm07pl6SNPz3S0",
    "latitude": 12.12345,
    "longitude": 15.12345
}

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "operation": {
            "id": "4158d533-e95a-4c05-a341-ef7d369d3a09",
            "authorization_code": "542010",
            "amount": 1000.55,
            "merchant_description": "CARGO POR COMISIONES"
        },
        "card": {
            "id": "11111111-daa7-1234-aaaa-123123123ecd",
            "masked_card_number": "************1234",
            "type": "PHYSICAL",
            "status": "ACTIVE"      
        },
        "account": {
            "id": "22222222-daa7-1234-aaaa-123123123ecd",
            "reference": 555555555
        }
    }
}

This operation allow you to apply a charge to a card. The charge is similar to Withdrawal, but allow you to specify a merchant description for the charge. This operation decrease your card's available balance and increases your collection balance account.

HTTP Request

POST /cards/purchase

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid The card_number or card_id that will receive the charge.
amount
required		 float digits The amount to charge
merchant_description
required		 string 1-32 characters The name or description of the charge
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the purchase is applyed. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the purchase is applyed. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180
pin
optional		 string 4 digits** The PIN if you need cardholder validation

Query card movements

Example JSON Request:

GET /cards/movements?initial_date=2021-07-01&end_date=2021-07-30&card_number=ab123d54-d87f-6d2c-7b02-1234e6ab123a

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "card": {
            "id": "11111111-daa7-1234-aaaa-123123123ecd",
            "masked_card_number": "************1234",
            "type": "PHYSICAL",
            "status": "ACTIVE"      
        },
        "account": {
            "id": "22222222-daa7-1234-aaaa-123123123ecd",
            "reference": 555555555
        },
        "movements": {
            "initial_date": "2021-07-01",
            "end_date": "2021-07-30",
            "detail": [
                {
                    "id": "123456789",
                    "referencial_id": "MASTER.MASTER_POS.1627686137.7753921.00000077.066147.1",
                    "date": "2021-07-30 17:03:02",
                    "code": {
                        "type": "1",
                        "subtype": "99",
                        "description": "ON Line - Compra"
                    },
                    "merchant": {
                        "code": "7898745",
                        "description": "ST*STRIPE 2  CIUDAD DE MEX MEX"
                    },
                    "country": {
                        "code": "484",
                        "description": "MEXICO  "
                    },
                    "amounts": {
                        "original": {
                            "coin": {
                                "code": "484",
                                "description": "Peso mexicano"
                            },
                            "total": "567.24"
                        },
                        "exchanged": {
                            "coin": {
                                "code": "484",
                                "description": "Peso mexicano"
                            },
                            "total": "567.24"
                        }
                    },
                    "channel": "MASTER_POS",
                    "authorization": "000000",
                    "status": {
                        "code": "00",
                        "description": "Aprobada"
                    },
                    "retrieval": "121212121212"
                }
            ]
        }
    }
}

This operation allow you query card movements between a date range.

HTTP Request

GET /cards/movements

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Query Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid The card_number or card_id that will receive the charge.
initial_date
required		 date YYYY-MM-DD Initial movements query date.
end_date
required		 date YYYY-MM-DD End movements query date.

Virtual Cards

Create a Virtual Card

Example JSON Request:

{
    "product":"4158d533-e95a-4c05-a341-ef7d369d3a09", 
    "cardholder_id": "ec123456-1qq2-1234-tt5g-8873fe52bf54",
    "document_type": "INE",
    "document_number": "123456123456",
    "observations": "",
    "latitude": 12.12345,
    "longitude": -15.12345
}

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
          "cardholder": {
              "id": "ab123456-1qq2-1234-tt5g-8873fe52bf54" ,
              "first_name": "John",
              "second_name": "Doe",
              "surname": "González",
              "second_surname": "Pérez",
              "rfc": "XAXX010101000",
              "curp": "XEXX010101HNEXXXA4"
          },
          "card": {
              "id": "11111111-daa7-1234-aaaa-123123123ecd",
              "type": "VIRTUAL", 
              "status": "NEED_ACTIVATION",
              "masked_card_number": "************1234",
              "card_number": "w98475n238c4u239874nc234p98c2m3084r238y46nx2p498y2n3984y304t503x4m237095",
              "exp_year": "klsdjfoisdjfowie48r2u9384uj4irth230984u5203985f235",
              "exp_month": "ñofhashfñgñoasirhgasohoqwhreoi234u5234j5234857234tj5r23i4p5jh235"
          },
          "account": {
               "id": "22222222-daa7-1234-aaaa-123123123ecd",
               "reference": "555555555",
               "clabe": null
          }
    }
}

This operation allow you to create a Virtual Card for a cardholder usually valid for E-Commerce purchases. You can use this cards also with the following services:
* Activate
* Change status
* Get Balance
* Get Info
* Authenticate cardholder
* Make transfer
* Make disbursement
* Make payment
* Make withdrawal
* Apply purchase

If SPEI® is allowed, you can call the following services:
* SPEI®

HTTP Request

POST /cards/virtual

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
product
required		 string uuid The product_id for the virtual card. See allowed values in Get Products
cardholder_id
required		 string uuid The cardholder's id.
document_type
required		 string Document Type The cardholder's document type to be registeres with the card. See allowed values in Get Document Type Catalog
document_number
required		 string 27 characters The document number belonging to the document type
observations
required		 string 0-100 characters Some comment about the card creation.
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the virtual card is created. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the virtual card is created. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180

Create physical card from virtual

Example JSON Request:

{
    "card_number": "t7wog3ytUb4pDQZT6AhE1USJab_-v7ut6AztPIH_SJK9gRETQQnFmqFPS-qcexyuRly0Hr9_jaG5YAnE_7CNNl_nbLYBi6YJvpnoZFSQdVgPaI0Pm07pl6SNPz3S0",
    "delivery_street": "Av. Siempre",
    "delivery_street_number": "#12 Lt3.",
    "delivery_township": "Benito Juárez",
    "delivery_state": "CDMX",
    "delivery_postal_code": "55120",
    "latitude": 12.12345,
    "longitude": 15.12354
}

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
         "card": {
              "id": "ab123456-1qq2-1234-tt5g-8873fe52bf54",
              "type": "VIRTUAL_WITH_PHYSICAL",
              "masked_card_number": "************1234"
          },
          "account": {
              "id": "22222222-daa7-1234-aaaa-123123123ecd",
              "rfc": "XAXX010101000",
              "curp": "XEXX010101HNEXXXA4",
              "primary_phone": "5555555555",
              "mobile_phone": "5555555555",
              "observations": "",
              "document": {
                  "type": "INE",
                  "description": "Instituto Nacional Electoral",
                  "number": "1236543212"
              }
          },
          "delivery_address": {
              "street": "Av. Siempre",
              "street_number": "#12 Lt3.",
              "township": "Benito Juárez",
              "state": "CDMX",
              "postal_code": "55120"
          }      
    }
}

This operation allow you to create a physical card from your virtual card. Depending on your program configuration and product, card can go to your main warehouse or directly to the cardholder delivery address.

HTTP Request

PUT /cards/virtual

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits** The card number for the card to request the physical card
delivery_street
required		 string 1-20 characters The delivery street for the card.
delivery_street_number
required		 string 1-10 characters The delivery street number for the card.
delivery_township
required		 string 1-25 characters The delivery township for the card.
delivery_state
required		 string States The delivery state for the card. See allowed values in Get States Catalog
delivery_postal_code
required		 string 5 digits The delivery postal code address for the card.
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the physical card request is made. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the physical card request is made. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180

Create Virtual Card CVC

Example JSON Request:

GET /cards/virtual/cvc?&card_number=11111111-daa7-1234-aaaa-123123123ecd&pin=1qUrzJd7ZoiTkegq4JWCoB-NP2qgxQzSnklalnTSEPPbPEhyR_y3zTup6ZTQto0FXE1ArtLPmntQ6-RKg&latitude=12.12345&longitude=15.13445

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
      "card": {
          "id": "11111111-daa7-1234-aaaa-123123123ecd",
          "masked_card_number": "************1234",
          "type": "VIRTUAL",
          "status": "ACTIVE",
          "cvc": "iufehqoiwuefhpqwi9ufuiphrpu235978234yrt32y049y98j57089f7h23847f5309",
          "remaining_time": "3"      
      },
      "account": {
          "id": "22222222-daa7-1234-aaaa-123123123ecd",
          "reference": 555555555
      }
    } 
}

This operation allow you to request a temporary cvc for a virtual card to authorize purchase operations. Before generate a valid CVC you need to set a ATM PIN first.

HTTP Request

GET /cards/virtual/cvc

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Query Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid The card number or card_id for the card to request the cvc.
pin
required		 string 4 digits** The ATM PIN for the card
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the cvv is requested. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the cvv is requested. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180

Clients

Get client information

Example JSON Request:

GET /clients

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "client": {
            "id": "65656565-ecb4-42d8-8555-858585858585",
            "name": "Capsule Corp.",
            "alias": "CAPCORP",
            "code": "CAPSU",
            "email": "[email protected]",
            "available": 1000000.51,
            "balance": 160.49,
            "time_zone": "America/Mexico_City",
            "status": "ACTIVE"
        }
    }
}

This operation allow you to query your registered client information.

HTTP Request

GET /clients

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Get your public key

Example JSON Request:

GET /clients/api_key/public_key

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "client": {
            "id": "12345abc-ebb5-56d8-3256-9875672a3455",
            "name": "CAPSULE CORP",
            "alias": "CAPSULE",
        },
        "api_key": {
            "id": "54321abc-abc5-56d8-6987-9875672a6587",
            "alias": "DEFAULT_API_KEY",
            "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuSH7IAJikX+jhtH8RROa\nWvwc4ISXXOCufLFk5DIrzK8thXpgAvFe9mg2J0kg5DSu0+FMLbfmmiMGsAElirs7\nK3LO2SgGLultdLdDcnlDNqXJNTJudhhVcAcIP93UBoN8XgH9rnqdXB4GXCGk5QCz\nV/Cfk6O8VyIKG9mGlRx5HJkPyjnJfrYptoNag9hMBc+TIfuhlOycG3+C1KdOUvsL\nQet6twHr0NBt8NyAOAP32v9slRFZS1tWn2ZcJMIfb+qYspcNhV1LB1CijHyjImaC\nOhyh3Cbf3/u7xv0qoHHmPcUmXniA9I+yA4taogx0NUE1pWjXqqtKjBhpS57leh60\nxQIDAQAB\n-----END PUBLIC KEY-----"
        },
        "system": {
            "public_key": "-----BEGIN PUBLIC KEY-----\nMIGTYAFSRW6RKAFGHYTRFDERTGTYTAR5FDSBCgKCAQEAuSH7IAJikX+jhtH8RROa\nWvwc4ISXXOCufLFk5DIrzK8thXpgAvFe9mg2J0kg5DSu0+FMLbfmmiMGsAElirs7\nK3LO2SgGLultdLdDcnlDNqXJNTJudhhVcAcIP93UBoN8XgH9rnqdXB4GXCGk5QCz\nV/Cfk6O8VyIKG9mGlRx5HJkPyjnJfrYptoNag9hMBc+TIfuhlOycG3+C1KdOUvsL\nQet6twHr0NBt8NyAOAP32v9slRFZS1tWn2ZcJMIfb+qYspcNhV1LB1CijHyjImaC\nOhyh3Cbf3/u7xv0qoHHmPcUmXniA9I+yA4taogx0NUE1pWjXqqtKjBhpS57leh60\nxQIDAQAB\n-----END PUBLIC KEY-----"
        },
        "sensitive_data": "odsfsodiurfopsjf0w9ierf0w9ef098409mrd0394u08923nxc98n23b8v2378rtn8274rtbxcbtc"
    }
}

This operation allow you to query your registered public key to allow system cipher sensitive data in responses and system public key to cipher sensitive data in your request. If a public key is not registered you can register one using Add Public Key.

HTTP Request

GET /clients/api_key/public_key

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Create a client

Example JSON Request:

{
  "name": "Noentiendo",
  "alias": "NOENT",
  "email": "[email protected]",
  "available": 1000,
  "phone": "5555555555",
  "mobile_phone": "6666666666",
  "rfc":  "AAMM9001010A1",
  "street": "Av. Siempre",
  "ext_street_number": "1234",
  "int_street_number": "Apt.4",
  "suburb": "Nápoles",
  "township": "Benito Juarez",
  "city": "CDMX",
  "state": "CDMX",
  "postal_code": "55555",
  "contact_name": "Juan",
  "contact_second_name": "Alberto",
  "contact_surname": "Perea",
  "contact_second_surname": "Perez",
  "contact_email": "[email protected]",
  "contact_telephone_country_code": 52,
  "contact_telephone": "5555555555",
  "contact_mobile_phone_country_code": 52,
  "contact_mobile_phone": "6666666666",
  "legal_representative_name": "Iman",
  "legal_representative_second_name": "Hora",
  "legal_representative_surname": "Martinez",
  "legal_representative_second_surname": "Martinez",
  "legal_representative_email": "[email protected]",
  "legal_representative_telephone_country_code": 52,
  "legal_representative_telephone": "5555555555",
  "legal_representative_mobile_phone_country_code": 52,
  "legal_representative_mobile_phone": "6666666666",
  "api_key_name": "SUB_CLIENT_ACCESS",
  "api_key_description": "Subclient Api Key",
  "api_key_password": "12345"
}

Example JSON Response:

{
  "success": true,
  "code": 0,
  "message": "OK",
  "data": {
    "subclient": {
      "id": "12345abc-ebb5-56d8-3256-9875672a3455",
      "code": "NOENT",
      "name": "Noentiendo",
      "available": 1000,
      "rfc": "AAMM9001010A1",
      "api_client": {
        "id": "",
        "name": "54321abc-abc5-56d8-6987-9875672a6587",
        "alias": "NOENT",
        "description": "Subclient Api Key"
      }
    }
  }
}

This operation allow you to create a subclient for your account. You need to have available balance to create a subclient.

HTTP Request

POST /clients

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
name
required		 string 5-30 characters The name of the company to be created
alias
required		 string 3-10 characters Alias for the company to be created
email
required		 string email Main email for the company
available
required		 float float number Initial available for the company
phone
required		 string 10 digits Main phone for the company
mobile_phone
required		 string 10 digits Main mobile phone for the company
rfc
required		 string 10-13 characters RFC of the company to be created
street
required		 string 1-20 characters Street name where the company is located
ext_street_number
required		 string 1-5 characters External street number where the company is located
int_street_number
optional		 string 1-5 characters Internal street number where the company is located
suburb
required		 string 1-25 characters Suburb where the company is located
township
required		 string 1-25 characters Township where the company is located
city
required		 string 1-25 characters City where the company is located
state
required		 string States The company state address. See allowed values in Get States Catalog
postal_code
required		 string 5 digits Postal code where the company is located
contact_name
required		 string 1-12 characters The name of the main contact for the company
contact_second_name
optional		 string 1-12 characters The second name of the main contact for the company
contact_surname
required		 string 1-12 characters The surname of the main contact for the company
contact_second_surname
optional		 string 1-12 characters The second surname of the main contact for the company
contact_email
required		 string email The email of the main contact for the company
contact_telephone_country_code
required		 string 2-3 digits The telephone country code of the main contact for the company
contact_telephone
required		 string 10 digits The telephone of the main contact for the company
contact_mobile_phone_country_code
required		 string 2-3 digits The mobile phone country code of the main contact for the company
contact_mobile_phone
required		 string 10 digits The mobile phone of the main contact for the company
legal_representative_name
optional		 string 1-12 characters The name of the legal representative for the company
legal_representative_second_name
optional		 string 1-12 characters The second name of the legal representative for the company
legal_representative_surname
optional		 string 1-12 characters The surname of the legal representative for the company
legal_representative_second_surname
optional		 string 1-12 characters The second surname of the legal representative for the company
legal_representative_email
optional		 string email The email of the legal representative for the company
legal_representative_telephone_country_code
optional		 string 2-3 digits The telephone country code of the legal representative for the company
legal_representative_telephone
optional		 string 10 digits The telephone of the legal representative for the company
legal_representative_mobile_phone_country_code
optional		 string 2-3 digits TThe mobile phone country code of the legal representative for the company
legal_representative_mobile_phone
optional		 string 10 digits The mobile phone of the legal representative for the company
api_key_name
required		 string 5-30 characters Api Key name for the company to be created
api_key_description
optional		 string 1-30 characters Description for the Api Key
api_key_password
required		 string 1-30 characters The Api Key password web service access

Add your public key

Example JSON Request:

{
    "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuSH7IAJikX+jhtH8RROa\nWvwc4ISXXOCufLFk5DIrzK8thXpgAvFe9mg2J0kg5DSu0+FMLbfmmiMGsAElirs7\nK3LO2SgGLultdLdDcnlDNqXJNTJudhhVcAcIP93UBoN8XgH9rnqdXB4GXCGk5QCz\nV/Cfk6O8VyIKG9mGlRx5HJkPyjnJfrYptoNag9hMBc+TIfuhlOycG3+C1KdOUvsL\nQet6twHr0NBt8NyAOAP32v9slRFZS1tWn2ZcJMIfb+qYspcNhV1LB1CijHyjImaC\nOhyh3Cbf3/u7xv0qoHHmPcUmXniA9I+yA4taogx0NUE1pWjXqqtKjBhpS57leh60\nxQIDAQAB\n-----END PUBLIC KEY-----"
}

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "client": {
            "id": "12345abc-ebb5-56d8-3256-9875672a3455",
            "name": "CAPSULE CORP",
            "alias": "CAPSULE"
        },
        "api_key": {
            "id": "15aad21d-f6fb-481e-bb12-ae3256987ff0",
            "alias": "DEFAULT_API_KEY",
            "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuSH7IAJikX+jhtH8RROa\nWvwc4ISXXOCufLFk5DIrzK8thXpgAvFe9mg2J0kg5DSu0+FMLbfmmiMGsAElirs7\nK3LO2SgGLultdLdDcnlDNqXJNTJudhhVcAcIP93UBoN8XgH9rnqdXB4GXCGk5QCz\nV/Cfk6O8VyIKG9mGlRx5HJkPyjnJfrYptoNag9hMBc+TIfuhlOycG3+C1KdOUvsL\nQet6twHr0NBt8NyAOAP32v9slRFZS1tWn2ZcJMIfb+qYspcNhV1LB1CijHyjImaC\nOhyh3Cbf3/u7xv0qoHHmPcUmXniA9I+yA4taogx0NUE1pWjXqqtKjBhpS57leh60\nxQIDAQAB\n-----END PUBLIC KEY-----"
        }
    }
}

This operation allow you to upload a public key to cipher sensitive data in responses. Certain services did not work if a public key is not loaded because the necessary information needs to be returned always ciphered. See Encryption for information about generate encryption/decryption keys.

HTTP Request

POST /clients/api_key/public_key

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
public_key
required		 string RSA public key Client's public key to be registered.

Fund a client

Example JSON Request:

{
    "client_id": "12345abc-ebb5-56d8-3256-9875672a3455", 
    "amount": 1200.50     
}

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "client": {
            "id": "12345abc-ebb5-56d8-3256-9875672a3455",
            "code": "CORP",
            "name": "CAPSULE CORP",
            "available": 50000,
            "rfc":  "XXXXXXXXXX"
        },
        "subclient": {
            "id": "15aad21d-f6fb-481e-bb12-ae3256987ff0",            
            "name": "RED RIBBON", 
            "code": "REDRI",
            "available": 1200.50 ,
            "rfc":  "YYYYYYYYYY"
        }
    }
}

If your program allow subclient creation, this operation let you top up the main account for your subclients subtracting the balance from your account and sending funds to your subclients account.

HTTP Request

POST /clients/fund

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
client_id
required		 string uuid Client's id to be funded.
amount
required		 float digits Amount to be funded.

SPEI®

Create SPEI®

Example JSON Request:

{
   "card_number": "11111111-daa7-1234-aaaa-123123123ecd",
    "payment_concept": "Pago de Renta",
    "beneficiary_account": "014027000005555558",
    "beneficiary_institution": "SANTANDER",
    "amount": 3000.25,
    "beneficiary_name": "John Doe",
    "numeric_reference": "12345" ,
    "beneficiary_rfc_curp": "ND",
    "beneficiary_email": "[email protected]",
    "latitude": 12.12345,
    "longitude": -15.12345
}

Example JSON Response:

{
        "success": true,
        "code": 0,
        "message": "OK",
        "data": {
            "card": {
                "card_id": "11111111-daa7-1234-aaaa-123123123ecd",
                "card_type": "PHISYCAL",
                "masked_card_number": "************1234"
            },
            "account": {
                "account_id": "22222222-daa7-1234-aaaa-123123123ecd",
                "rfc": "XAXX010101000",
                "curp": "XEXX010101HNEXXXA4",
                "primary_phone": "5555555555",
                "mobile_phone": "5555555555",
                "observations":  ""
            },
            "spei": {
                "id": "123456",
                "tracking_key": "ABM123456789",
                "operation_date": "2021-01-01",
                "reference_operation": "ab123456-1qq2-1234-tt5g-8873fe52bf54",
                "amount": 3000.25,
                "commission": 5.80,
                "commission_type": "FLAT",
                "iva":   0.93
            }
        }
}

If your program has SPEI service enabled, this operation allow you to make an "Interbanking Transfer" from a card to any Mexican Bank part of Mexican Bank Association (Asociación de Bancos de México – ABM).

HTTP Request

POST /spei

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Body Parameters

Parameter Type Pattern Description
card_number
required		 string 16 digits* or uuid Sender's card number or card_id
payment_concept
required		 string 1-40 characters Transfer payment concept
beneficiary_account
required		 string 10, 16 or 18 digits Beneficiary's account, can be phone, card number or CLABE
beneficiary_institution
required		 string SPEI Institucions Beneficiary's bank institution
amount
required		 float digits Amount to transfer
beneficiary_name
required		 string 1-40 characters Beneficiary's account name
numeric_reference
required		 string 1-7 digits Numeric reference for payment
beneficiary_rfc_curp
required		 string 'ND', 10-13 or 18 characters Beneficiary's RFC or CURP. If not known use 'ND' string
beneficiary_email
required		 string email Beneficiary's email
latitude
required		 float Digits format "DD.ddddd" (5 decimal precision) Latitude from where the spei is requested. South latitudes are preceded by a minus sign. Latitudes range from -90 to 90
longitude
required		 float Digits format "DDD.ddddd" (5 decimal precision) Longitude from where the spei is requested. West longitudes are preceded by a minus sign. Longitudes range from -180 to 180

Get SPEI® Institutions

Example JSON Request:

GET /spei/institutions

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "spei_institutions": [
            {
                "inicio_clabe": "006",
                "clave_institucion": "37006",
                "nombre_institucion": "BANCOMEXT"
            }
         ]
    }
}

This endpoint retrieves the bank institution catalog.

HTTP Request

GET /spei/institutions

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Products

GET products

Example JSON Request:

GET /products

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "products": {
            "total": 1,
            "detail": [
                {
                    "id": "365d568a-4567-123e-81dc-987654bf1234",
                    "name": "SUPER PRODUCTO PREMIUM",
                    "description": "",
                    "country": {
                        "code": "484",
                        "description": null
                    },
                    "coin": {
                        "code": "484",
                        "description": "PESO MEXICANO"
                    },
                    "type": {
                        "key": "DEBIT_2",
                        "value": "Debito 2"
                    },
                    "status": {
                        "key": "ACTIVE",
                        "value": "activo"
                    },
                    "affinity_group": "0003",
                    "stock_cards": 0,
                    "allow_blank_curp": false,
                    "allow_blank_rfc": false
                }
            ]
        }
    }
}

This endpoint allow you to query all your assigned or created products.

HTTP Request

GET /products

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Catalogs

Get card statuses

Example JSON Request:

GET /catalogs/card_status

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "card_status": [
            {
                "key": "ACTIVE",
                "value": "01",
                "description": ""
            },
            {  
                "key": "TEMPORARY_INACTIVE",
                "value": "2N",
                "description": ""
            }
        ]
    }  
}

This operation allow you to get the card statuses catalog information.

HTTP Request

GET /catalogs/card_status

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Get document types

Example JSON Request:

GET /catalogs/document_types

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "document_type": [
            {
                "key": "INE",
                "value": "INE",
                "description": ""
            },
            {  
                "key": "IFE",
                "value": "IFE",
                "description": ""
            }
        ]
    }  
}

This operation allow you to get the Document Types catalog information.

HTTP Request

GET /catalogs/document_type

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

Get states

Example JSON Request:

GET /catalogs/states

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "states": [
            {
                "key": "CDMX",
                "value": "A",
                "description": ""
            },
            {  
                "key": "AGUASCALIENTES",
                "value": "B",
                "description": ""
            }
        ]
    }  
}

This operation allow you to get the States catalog information.

HTTP Request

GET /catalogs/states

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

GET marital status

Example JSON Request:

GET /catalogs/marital_status

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "marital_status": [
            {
                "key": "SOLTERO",
                "value": "S",
                "description": ""
            },
            {  
                "key": "CASADO",
                "value": "C",
                "description": ""
            }
        ]
    }  
}

This operation allow you to get the marital statuses catalog information.

HTTP Request

GET /catalogs/marital_status

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

GET gender

Example JSON Request:

GET /catalogs/gender

Example JSON Response:

{
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
        "gender": [
            {
                "key": "MALE",
                "value": "MALE",
                "description": ""
            },
            {  
                "key": "FEMALE",
                "value": "FEMALE",
                "description": ""
            }
        ]
    }  
}

This operation allow you to get the gender catalog information.

HTTP Request

GET /catalogs/gender

Header Parameters

Header Description
Authorization
required		 The Bearer token created in Get authorization Token
Content-Type
required		 application/json

HTTP Codes

All the CIMAPI calls return one of the following http codes:

HTTP Code Meaning
200 Ok -- Your request was executed successfully!.
201 Created -- Your resource was successfully created!.
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The operation or resource was valid, but an error has occurred.
404 Not Found -- The specified operation or resource could not be found.
405 Method Not Allowed -- You tried to access an operation with an invalid method.
422 Unprocessable Entity -- Your request syntax is valid, but has invalid fields.
429 Too Many Requests -- You're requesting too many things! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
json