Create Card

This route is used to validate customer data along with their card in our Antifraud system. Once validated, this card is securely saved in Marlim's vault for use in future purchases. After saving the card, you receive an object containing a hash in the card_id property.

One Click Buy

This is the best way to implement One Click Buy. With the card_id on our server, your customer won't need to enter card data again and will be able to purchase with just one click, avoiding sensitive data transmission online.
Cool, right? 😎

Production Environment

This version of the Create Cards API (v3) for the production environment is still under development. To get information about the release schedule for this functionality, contact the Marlim team through our support channels.

POSTv3/cards

Request Body Params

Attribute	Type	Description
card_holder_name	string	Cardholder name.
card_number	string	Card number.
card_expiration_date	string	Card expiration date. Numbers only in MMYY format.
card_cvv	string	Card verification code.

Request Body Example

{
  "card_holder_name": "John Doe",
  "card_number": "1234567890123456",
  "card_expiration_date": "1225",
  "card_cvv": "123"
}

Important

Our API does not accept null, undefined or empty string values in any endpoint. If you pass a parameter with any of these 3 values, an error will be returned. If the parameter is not mandatory and you don't want it to be computed, simply remove it from the request.

Response Object

Property	Type	Description
card_id	string	Card identifier hash.
date_created	dateTime	Card creation date in ISODateTime format.
date_updated	dateTime	Card update date in ISODateTime format.
card_holder_name	string	Cardholder name.
card_brand	string	Card brand. Possible values: visa, mastercard, amex, hipercard and elo.
card_first_digits	string	First 6 digits of the card.
card_last_digits	string	Last 4 digits of the card.
card_expiration_date	string	Card expiration date in MMYY format.
valid	boolean	Property to verify card validity, that is, if true, the card can be charged under normal conditions, if false, it cannot be used.

Response Example

{
  "card_id": "card_princess12leia45organa678",
  "date_created": "2025-01-01T00:00:00.000Z",
  "date_updated": "2025-01-01T00:00:00.000Z",
  "card_holder_name": "Leia S O Solo",
  "card_brand": "mastercard",
  "card_first_digits": "444455",
  "card_last_digits": "3333",
  "card_expiration_date": "1122",
  "valid": true
}

Error Object

Attribute	Type	Description
api_reference	string	URL for documentation.
errors	array	Array with all errors found when processing the request.
errors[][type]	string	Type of error that occurred.
errors[][message]	string	Detailed error message.

Error Example

{
    "api_reference": "https://docs.api.marlim.co/cards/read",
    "errors": [
        {
            "type": "card_holder_name",
            "message": "The parameter [ card_holder_name ] is missing."
        },
    ]
}

Examples

WARNING

The values used in the examples below are for illustration purposes only and should not be used to make requests to Marlim APIs. In development and testing environments, use data closer to a real transaction.

Card Created

Request

curl -X POST "https://api.marlim.co/v3/cards" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "card_holder_name": "Leia S O Solo",
  "card_number": "4444555566663333",
  "card_expiration_date": "0504",
  "card_cvv": "999"
}'

Response200

{
  "card_id": "card_princess12leia45organa678",
  "date_created": "2025-07-29T11:38:57.563Z",
  "date_updated": "2025-07-29T11:38:57.563Z",
  "card_holder_name": "Leia S O Solo",
  "card_brand": "mastercard",
  "card_first_digits": "444455",
  "card_last_digits": "3333",
  "card_expiration_date": "1122",
  "valid": true
}

Missing Parameters

Request

curl -X POST "https://api.marlim.co/v3/cards" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "card_holder_name": "Han Solo",
  "card_number": "1243291243298888",
  "card_expiration_date": "0504"
}'

Response400

{
  "api_reference": "https://docs.api.marlim.co/cards/create",
  "errors": [
    {
      "type": "card_cvv",
      "message": "The parameter [ card_cvv ] is missing."
    }
  ]
}