---
agentTools:
projectIndex: https://docs.mundipagg.com/llms.txt
---
# Criar cartão
Este recurso cria um `card` associado ao `customer` através do `customer_id` informado.
[block:callout]
{
"type": "warning",
"title": "Falha na verificação de cartão",
"body": "Quando a verificação de cartão esta ativa e ocorre uma falha na verificação, a API irá retornar erro \"412\" com a mensagem: \"Could not create credit card. The card verification failed.\""
}
[/block]
[block:callout]
{
"type": "warning",
"title": "Cartão já cadastrado",
"body": "Caso um cliente tente cadastrar um **mesmo cartão mais de uma vez***, será retornado o mesmo `card_id` do cartão previamente cadastrado."
}
[/block]
[block:callout]
{
"type": "danger",
"body": "Caso o cartão seja _private label_ (ou seja `private_label` = **true**), `brand` será um campo obrigatório.",
"title": "Campo \"brand\" é obrigatório para cartões Private Label"
}
[/block]
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Mundipagg API",
"version": "1"
},
"servers": [
{
"url": "https://api.mundipagg.com/core/v1"
}
],
"components": {
"securitySchemes": {
"sec0": {
"type": "http",
"scheme": "basic"
}
}
},
"security": [
{
"sec0": []
}
],
"paths": {
"/customers/{customer_id}/cards": {
"post": {
"summary": "Criar cartão",
"description": "Este recurso cria um `card` associado ao `customer` através do `customer_id` informado.",
"operationId": "criar-cartao",
"parameters": [
{
"name": "customer_id",
"in": "path",
"description": "Código do cliente. Formato: `cus_XXXXXXXXXXXXXXXX`",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"number",
"exp_month",
"exp_year"
],
"properties": {
"number": {
"type": "string",
"description": "Número do cartão. Entre 13 e 19 caracteres"
},
"holder_name": {
"type": "string",
"description": "Nome do portador como está impresso no cartão. Máximo de 64 caracteres (Caracteres especiais e números não são aceitos)"
},
"holder_document": {
"type": "string",
"description": "CPF ou CNPJ do portador do cartão. Obrigatório caso o tipo do cartão seja voucher (bandeiras **VR** ou **Sodexo**)."
},
"exp_month": {
"type": "integer",
"description": "Mês de validade do cartão. Valor entre 1 e 12 (inclusive)",
"format": "int32"
},
"exp_year": {
"type": "integer",
"description": "Ano de validade do cartão. Formatos **yy** ou **yyyy**. Ex: 23 ou 2023.",
"format": "int32"
},
"cvv": {
"type": "string",
"description": "Código de segurança do cartão. O campo aceita 4 ou 3 caracteres, variando por bandeira."
},
"brand": {
"type": "string",
"description": "Bandeira do cartão. Para cartões de crédito, temos como valores possíveis: **Elo**, **Mastercard**, **Visa**, **Amex**, **JCB**, **Aura**, **Hipercard**, **Diners** ou **Discover**. Para voucher, temos como valores possíveis: **Alelo**, **VR** ou **Sodexo**."
},
"label": {
"type": "string",
"description": "Indica a label do cartão"
},
"billing_address_id": {
"type": "string",
"description": "Código do endereço de cobrança. Max: 36 caracteres.<>**Opcional**, pode ser utilizado no lugar do `billing_address`."
},
"billing_address": {
"type": "object",
"description": "Endereço de cobrança.",
"properties": {}
},
"options": {
"type": "object",
"description": "Objeto com opções para a criação do cartão. Um exemplo de opção que pode ser adicionada ao cartão é o `verify_card` : `true`, que informa que haverá uma validação do cartão antes da utilização (Zero Dollar Auth).",
"properties": {}
},
"metadata": {
"type": "object",
"description": "Objeto chave/valor utilizado para armazenar informações adicionais sobre o cartão. [Saiba mais sobre metadata](https://docs.mundipagg.com/v1/reference#metadata)",
"properties": {}
},
"token": {
"type": "string",
"description": "Pode ser enviado no lugar dos dados do cartão, caso este já tenha sido tokenizado previamente. [Saiba mais sobre criação de token de cartão.](https://docs.mundipagg.com/reference#criar-token-cartao)"
}
}
},
"examples": {
"JSON": {
"value": {
"number": "4000000000000010",
"holder_name": "Tony Stark",
"holder_document": "93095135270",
"exp_month": 1,
"exp_year": 30,
"cvv": "351",
"brand": "Mastercard",
"label": "Sua bandeira",
"billing_address": {
"line_1": "375, Av. General Osorio, Centro",
"line_2": "7º Andar",
"zip_code": "220000111",
"city": "Rio de Janeiro",
"state": "RJ",
"country": "BR"
},
"options": {
"verify_card": true
}
}
},
"JSON (with Card Token)": {
"value": {
"token": "token_e30oNGXu7I7LRgar",
"options": {
"verify_card": true
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "200",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"id\": \"card_8ELY0AwVF9HDa3jK\",\n \"first_six_digits\": \"542501\",\n \"last_four_digits\": \"7793\",\n \"brand\": \"Mastercard\",\n \"holder_name\": \"Tony Stark\",\n \"holder_document\": \"93095135270\",\n \"exp_month\": 1,\n \"exp_year\": 2030,\n \"status\": \"active\",\n \"label\": \"Sua bandeira\",\n \"created_at\": \"2017-07-07T19:50:33Z\",\n \"updated_at\": \"2017-07-07T19:50:33Z\",\n \"billing_address\": {\n \"zip_code\": \"220000111\",\n \"city\": \"Rio de Janeiro\",\n \"state\": \"RJ\",\n \"country\": \"BR\",\n \"line_1\": \"375, Av. General Osorio, Centro\",\n \"line_2\": \"7º Andar\"\n },\n \"customer\": {\n \"id\": \"cus_yoqONwOJI1IBNbjl\",\n \"name\": \"Tony Stark\",\n \"email\": \"0fee2dc5-e440-4dd1-9cd6-9c2bc90533d0@avengers.com\",\n \"document\": \"93095135270\",\n \"type\": \"individual\",\n \"delinquent\": false,\n \"created_at\": \"2017-07-07T19:50:23Z\",\n \"updated_at\": \"2017-07-07T19:50:23Z\",\n \"phones\": {\n \"home_phone\": {\n \"country_code\": \"55\",\n \"number\": \"000000000\",\n \"area_code\": \"21\"\n },\n \"mobile_phone\": {\n \"country_code\": \"55\",\n \"number\": \"000000000\",\n \"area_code\": \"21\"\n }\n },\n \"metadata\": {\n \"company\": \"Avengers\"\n }\n },\n \"type\": \"credit\"\n}"
}
},
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "card_8ELY0AwVF9HDa3jK"
},
"first_six_digits": {
"type": "string",
"example": "542501"
},
"last_four_digits": {
"type": "string",
"example": "7793"
},
"brand": {
"type": "string",
"example": "Mastercard"
},
"holder_name": {
"type": "string",
"example": "Tony Stark"
},
"holder_document": {
"type": "string",
"example": "93095135270"
},
"exp_month": {
"type": "integer",
"example": 1,
"default": 0
},
"exp_year": {
"type": "integer",
"example": 2030,
"default": 0
},
"status": {
"type": "string",
"example": "active"
},
"label": {
"type": "string",
"example": "Sua bandeira"
},
"created_at": {
"type": "string",
"example": "2017-07-07T19:50:33Z"
},
"updated_at": {
"type": "string",
"example": "2017-07-07T19:50:33Z"
},
"billing_address": {
"type": "object",
"properties": {
"zip_code": {
"type": "string",
"example": "220000111"
},
"city": {
"type": "string",
"example": "Rio de Janeiro"
},
"state": {
"type": "string",
"example": "RJ"
},
"country": {
"type": "string",
"example": "BR"
},
"line_1": {
"type": "string",
"example": "375, Av. General Osorio, Centro"
},
"line_2": {
"type": "string",
"example": "7º Andar"
}
}
},
"customer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "cus_yoqONwOJI1IBNbjl"
},
"name": {
"type": "string",
"example": "Tony Stark"
},
"email": {
"type": "string",
"example": "0fee2dc5-e440-4dd1-9cd6-9c2bc90533d0@avengers.com"
},
"document": {
"type": "string",
"example": "93095135270"
},
"type": {
"type": "string",
"example": "individual"
},
"delinquent": {
"type": "boolean",
"example": false,
"default": true
},
"created_at": {
"type": "string",
"example": "2017-07-07T19:50:23Z"
},
"updated_at": {
"type": "string",
"example": "2017-07-07T19:50:23Z"
},
"phones": {
"type": "object",
"properties": {
"home_phone": {
"type": "object",
"properties": {
"country_code": {
"type": "string",
"example": "55"
},
"number": {
"type": "string",
"example": "000000000"
},
"area_code": {
"type": "string",
"example": "21"
}
}
},
"mobile_phone": {
"type": "object",
"properties": {
"country_code": {
"type": "string",
"example": "55"
},
"number": {
"type": "string",
"example": "000000000"
},
"area_code": {
"type": "string",
"example": "21"
}
}
}
}
},
"metadata": {
"type": "object",
"properties": {
"company": {
"type": "string",
"example": "Avengers"
}
}
}
}
},
"type": {
"type": "string",
"example": "credit"
}
}
}
}
}
},
"404": {
"description": "404",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"message\": \"Customer not found.\"\n}"
}
},
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Customer not found."
}
}
}
}
}
},
"422": {
"description": "422",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"message\": \"The request is invalid.\",\n \"errors\": {\n \"card\": [\n \"The card expiration date is invalid.\"\n ]\n },\n \"request\": {\n \"number\": \"5425019448107793\",\n \"last_four_digits\": \"7793\",\n \"brand\": \"Mastercard\",\n \"holder_name\": \"Tony Stark\",\n \"exp_month\": 1,\n \"cvv\": \"123\",\n \"billing_address\": {\n \"zip_code\": \"220000111\",\n \"city\": \"Rio de Janeiro\",\n \"state\": \"RJ\",\n \"country\": \"BR\",\n \"line_1\": \"375, Av. General Osorio, Centro\",\n \"line_2\": \"7º Andar\"\n },\n \"options\": {\n \"verify_card\": true\n }\n }\n}"
}
},
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "The request is invalid."
},
"errors": {
"type": "object",
"properties": {
"card": {
"type": "array",
"items": {
"type": "string",
"example": "The card expiration date is invalid."
}
}
}
},
"request": {
"type": "object",
"properties": {
"number": {
"type": "string",
"example": "5425019448107793"
},
"last_four_digits": {
"type": "string",
"example": "7793"
},
"brand": {
"type": "string",
"example": "Mastercard"
},
"holder_name": {
"type": "string",
"example": "Tony Stark"
},
"exp_month": {
"type": "integer",
"example": 1,
"default": 0
},
"cvv": {
"type": "string",
"example": "123"
},
"billing_address": {
"type": "object",
"properties": {
"zip_code": {
"type": "string",
"example": "220000111"
},
"city": {
"type": "string",
"example": "Rio de Janeiro"
},
"state": {
"type": "string",
"example": "RJ"
},
"country": {
"type": "string",
"example": "BR"
},
"line_1": {
"type": "string",
"example": "375, Av. General Osorio, Centro"
},
"line_2": {
"type": "string",
"example": "7º Andar"
}
}
},
"options": {
"type": "object",
"properties": {
"verify_card": {
"type": "boolean",
"example": true,
"default": true
}
}
}
}
}
}
}
}
}
}
},
"deprecated": false,
"x-readme": {
"code-samples": [
{
"language": "csharp",
"code": "using MundiAPI.PCL;\nusing MundiAPI.PCL.Models;\nusing System.Collections.Generic;\nusing System.Web.Mvc;\n\nnamespace MundipaggTest.Controllers {\n\npublic class HomeController : Controller {\n\npublic ActionResult Index() {\n\n // Secret key fornecida pela Mundipagg\n string basicAuthUserName = \"SUA_CHAVE_SECRETA\";\n\n // Senha em branco. Passando apenas a secret key\n string basicAuthPassword = \"\";\n\n var client = new MundiAPIClient(basicAuthUserName, basicAuthPassword);\n\n string customerId = \"cus_6l5dMWZ0hkHZ4XnE\";\n var metadata = new Dictionary();\n metadata.Add(\"company\", \"Avengers\");\n\n var billingAddress = new CreateAddressRequest {\n Line1 = \"375, Av. General Justo, Centro\",\n Line2 = \"7º andar\",\n ZipCode = \"22000111\",\n City = \"Rio de Janeiro\",\n State = \"RJ\",\n Country = \"BR\"\n };\n\n var request = new CreateCardRequest {\n Number = \"5425019448107793\",\n HolderName = \"Tony Stark\",\n ExpMonth = 1,\n ExpYear = 30,\n Cvv = \"351\",\n Brand = \"Mastercard\",\n PrivateLabel = false,\n BillingAddress = billingAddress,\n Metadata = metadata,\n };\n\n var response = client.Customers.CreateCard(customerId, request);\n \n return View();\n}\n}\n}",
"name": "SDK C#"
},
{
"language": "php",
"code": "//This example was built using MundiAPI-PHP SDK.\n//For more information, please refer to https://github.com/mundipagg/MundiAPI-PHP\n\n$secretKey = 'YOUR_SECRET_KEY'; //the secret key will be provided by MundiPagg.\n$basicAuthPassword = ''; //fill it with an empty string\n\n$apiClient = new \\MundiAPILib\\MundiAPIClient(\n $secretKey,\n $basicAuthPassword\n);\n\n$customerController = $apiClient->getCustomers();\n\n$customer = new \\MundiAPILib\\Models\\CreateCustomerRequest();\n$customer->name = \"sdk customer test\";\n$customer->email = \"tonystark@avengers.com\";\n\n$request = new \\MundiAPILib\\Models\\CreateCardRequest();\n\n$request->number = \"4000000000000010\";\n$request->holderName = \"Tony Stark\";\n$request->holderDocument = \"93095135270\";\n$request->expMonth = 1;\n$request->expYear = 30;\n$request->cvv = \"351\";\n// Brand is Optional field and autodetected;\n$request->brand = \"Mastercard\";\n$request->privateLabel = false;\n// Billing Address;\n$request->billingAddress = new \\MundiAPILib\\Models\\CreateAddressRequest();\n$request->billingAddress->line1 = \"375, Av. General Osorio, Centro\";\n$request->billingAddress->line2 = \"7º Andar\";\n$request->billingAddress->zipCode = \"220000111\";\n$request->billingAddress->city = \"Rio de Janeiro\";\n$request->billingAddress->state = \"RJ\";\n$request->billingAddress->country = \"BR\";\n// Card Options: Verify OneDollarAuth;\n$request->options = new \\MundiAPILib\\Models\\CreateCardOptionsRequest();\n$request->options->verifyCard = true;\n\n$createdCustomer = $customerController->createCustomer($customer);\n$result = $customerController->createCard($createdCustomer->id, $request);\n\necho json_encode($result, JSON_PRETTY_PRINT);",
"name": "SDK PHP"
},
{
"language": "python",
"code": "from mundiapi.mundiapi_client import MundiapiClient\nfrom mundiapi.models import *\nfrom mundiapi.controllers import *\nfrom mundiapi.exceptions.error_exception import *\n\nMundiapiClient.config.basic_auth_user_name = \"YOUR_SECRET_KEY:\"\ncustomers_controller = customers_controller.CustomersController()\n\ncustomer = create_customer_request.CreateCustomerRequest()\ncustomer.name = \"sdk customer test\"\ncustomer.email = \"tonystark@avengers.com\"\n\nrequest = create_card_request.CreateCardRequest()\n\nrequest.number = \"4000000000000010\"\nrequest.holder_name = \"Tony Stark\"\nrequest.holder_document = \"93095135270\"\nrequest.exp_month = 1\nrequest.exp_year = 30\nrequest.cvv = \"351\"\nrequest.brand = \"Mastercard\"\nrequest.private_label = False\n# Billing Address\nrequest.billing_address = create_address_request.CreateAddressRequest()\nrequest.billing_address.line_1 = \"375 Av. General Osorio Centro\"\nrequest.billing_address.line_2 = \"7º Andar\"\nrequest.billing_address.zip_code = \"220000111\"\nrequest.billing_address.city = \"Rio de Janeiro\"\nrequest.billing_address.state = \"RJ\"\nrequest.billing_address.country = \"BR\"\n# Card Options\nrequest.options = create_card_options_request.CreateCardOptionsRequest()\nrequest.options.verify_card = True\n\ntry:\n createdCustomer = customers_controller.create_customer(customer)\n result = customers_controller.create_card(createdCustomer.id, request)\n assert createdCustomer is not None\n assert result is not None\n print(\"Customer id: \", createdCustomer.id)\n print(\"Card id: \", result.id)\n\nexcept ErrorException as ex:\n print(ex.message)\n print(\"Errors: \", ex.errors)\nexcept Exception as ex:\n raise ex",
"name": "SDK PYTHON"
}
],
"samples-languages": [
"csharp",
"php",
"python"
]
}
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": false,
"proxy-enabled": false
},
"x-readme-fauxas": true,
"_id": "5aba89f6b169810058a71e9a:5aba89f6b169810058a71ea7"
}
```