---
updatedAt: 2026-09-17T16:31:23.000Z
agentTools:
  projectIndex: https://docs.dlocal.com/llms.txt
---

# Create a card

Securely register a card with dLocal and receive a `card_id` to use for future payments.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Payins",
    "version": "2.1"
  },
  "servers": [
    {
      "url": "https://api.dlocal.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "name": "X-Date",
        "in": "header",
        "x-default": ""
      },
      "sec1": {
        "type": "apiKey",
        "name": "X-Login",
        "in": "header",
        "x-default": ""
      },
      "sec2": {
        "type": "apiKey",
        "name": "X-Trans-Key",
        "in": "header",
        "x-default": ""
      },
      "sec3": {
        "type": "apiKey",
        "name": "Content-Type",
        "in": "header",
        "x-default": "application/json"
      },
      "sec4": {
        "type": "apiKey",
        "name": "X-Version",
        "in": "header",
        "x-default": "2.1"
      },
      "sec5": {
        "type": "apiKey",
        "name": "User-Agent",
        "in": "header",
        "x-default": ""
      },
      "sec6": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header",
        "x-default": ""
      }
    }
  },
  "security": [
    {
      "sec0": [],
      "sec1": [],
      "sec2": [],
      "sec3": [],
      "sec4": [],
      "sec5": [],
      "sec6": []
    }
  ],
  "paths": {
    "/secure_cards": {
      "post": {
        "tags": [
          "Saving cards"
        ],
        "summary": "Create a card",
        "description": "Securely register a card with dLocal and receive a `card_id` to use for future payments.",
        "operationId": "create-a-card",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "card",
                  "payer",
                  "country"
                ],
                "properties": {
                  "country": {
                    "type": "string",
                    "description": "Payment processing country code. ISO 3166-1 alpha-2 code."
                  },
                  "card": {
                    "type": "object",
                    "description": "The Card Object",
                    "required": [
                      "holder_name",
                      "expiration_month",
                      "expiration_year",
                      "number",
                      "cvv"
                    ],
                    "properties": {
                      "holder_name": {
                        "type": "string",
                        "description": "Cardholder's full name."
                      },
                      "expiration_month": {
                        "type": "integer",
                        "description": "Two digit number representing the card's expiration month.",
                        "format": "int32"
                      },
                      "expiration_year": {
                        "type": "integer",
                        "description": "Four digit number representing the card's expiration year.",
                        "format": "int32"
                      },
                      "number": {
                        "type": "string",
                        "description": "The card number, as a string without any separators."
                      },
                      "cvv": {
                        "type": "string",
                        "description": "Credit card verification value."
                      },
                      "encrypted_data": {
                        "type": "string",
                        "description": "JWE ​encrypted params."
                      },
                      "token": {
                        "type": "string",
                        "description": "Temporary credit card token securely created using Smart Fields."
                      },
                      "cvv_token": {
                        "type": "string",
                        "description": "Temporary CVV token securely created using the CVV-only Smart Field."
                      }
                    }
                  },
                  "payer": {
                    "type": "object",
                    "description": "The Payer Object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "description": "User's full name.</br></br>Length: 100.</br>India-compliant length: 3 to 50 (e.g., Gaurav Kumar)."
                      },
                      "email": {
                        "type": "string",
                        "description": "User’s email address.</br></br>Length: 100.</br>India-compliant length:  64 max for the username (e.g., in `gaurav.kumar@example.com`, \"gaurav.kumar\" must not exceed 64 characters)."
                      },
                      "birth_date": {
                        "type": "string",
                        "description": "User’s birthdate (DD-MM-YYYY). Mandatory for cross-border payment processing in India as per PACB regulations.</br></br>Length: 10."
                      },
                      "phone": {
                        "type": "string",
                        "description": "User’s phone. Mandatory for Wallets and cross-border (PACB) transactions in India. Also required for fraud prevention. </br></br>Length: 20.</br>India-compliant length: 15 max (e.g., +919123456780)."
                      },
                      "document": {
                        "type": "string",
                        "description": "User’s personal identification number. Mandatory for cross-border (PACB) transactions in India.</br></br>To see the document code list per country, go to the [Country Reference page](ref:country-reference).</br></br>Length: 30."
                      },
                      "document2": {
                        "type": "string",
                        "description": "Additional personal identification.</br></br>To see the document code list per country, go to the [Country Reference page](ref:country-reference)."
                      },
                      "address": {
                        "type": "object",
                        "description": "User’s address. Required in India for cross-border (PACB) transactions for fraud prevention, and in South Africa for fraud prevention.",
                        "properties": {
                          "state": {
                            "type": "string",
                            "description": "User's address state. Required in India for cross-border (PACB) transactions and in South Africa. </br></br>Length: 10.</br>India-compliant length: 10 max (e.g., Karnataka)."
                          },
                          "city": {
                            "type": "string",
                            "description": "User’s address city. Required in India for cross-border (PACB) transactions and in South Africa. </br></br>Length: 100.</br>India-compliant length: 3 to 50 (e.g., Bengaluru)."
                          },
                          "zip_code": {
                            "type": "string",
                            "description": "User’s address ZIP Code. Required in India for cross-border (PACB) transactions and in South Africa.</br></br>Length: 10.</br>Must be exactly 6 numeric digits for India (e.g., 560032)."
                          },
                          "street": {
                            "type": "string",
                            "description": "User’s address street. Required in India for cross-border (PACB) transactions and in South Africa.</br></br>Length: 100.</br>India-compliant length: 4 to 100 (e.g., Mantri apartment Koramangala)."
                          },
                          "number": {
                            "type": "string",
                            "description": "User’s address number. Required in India for cross-border (PACB) transactions and in South Africa.</br></br>Length: 20.</br>India-compliant length: 20 (e.g., 35)."
                          }
                        }
                      },
                      "ip": {
                        "type": "string",
                        "description": "User's IP address. Required for fraud prevention. </br></br>Length: 39."
                      },
                      "device_id": {
                        "type": "string",
                        "description": "User's unique device identifier. Required for fraud prevention.</br></br>Length: 25."
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"holder_name\": \"Thiago Gabriel\",\n  \"expiration_month\": 10,\n  \"expiration_year\": 2040,\n  \"brand\": \"VI\",\n  \"last4\": \"1111\",\n  \"card_id\": \"CID-2210908e-6d8e-468d-9eb3-d551e8b541a0\",\n  \"country\": \"BR\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "holder_name": {
                      "type": "string",
                      "example": "Thiago Gabriel"
                    },
                    "expiration_month": {
                      "type": "integer",
                      "example": 10,
                      "default": 0
                    },
                    "expiration_year": {
                      "type": "integer",
                      "example": 2040,
                      "default": 0
                    },
                    "brand": {
                      "type": "string",
                      "example": "VI"
                    },
                    "last4": {
                      "type": "string",
                      "example": "1111"
                    },
                    "card_id": {
                      "type": "string",
                      "example": "CID-2210908e-6d8e-468d-9eb3-d551e8b541a0"
                    },
                    "country": {
                      "type": "string",
                      "example": "BR"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    “code” : 5001,\n    “message” : \"Invalid parameter\",\n    “param” : \"card.number\"\n}"
                  }
                }
              }
            }
          }
        },
        "deprecated": false,
        "x-readme": {
          "code-samples": [
            {
              "language": "shell",
              "code": "curl -X POST \\\n   -H 'X-Date: {X-Date}' \\\n   -H 'X-Login: {X-Login}' \\\n   -H 'X-Trans-Key: {X-Trans-Key}' \\\n   -H 'Content-Type: application/json' \\\n   -H 'X-Version: 2.1' \\\n   -H 'User-Agent: MerchantTest / 1.0 ' \\\n   -H 'Authorization: V2-HMAC-SHA256, Signature: {Signature}' \\\n   -d '{body}'\n    https://api.dlocal.com/secure_cards\n{\n    \"country\": \"BR\",\n    \"card\": {\n        \"holder_name\": \"Thiago Gabriel\",\n        \"expiration_month\": 10,\n        \"expiration_year\": 2040,\n        \"number\": \"4111111111111111\",\n        \"cvv\": \"123\"\n    },\n    \"payer\": {\n        \"name\": \"Luis Gabriel\",\n        \"document\": \"53033315550\",\n        \"email\": \"luis@email.com\"\n    }\n}"
            }
          ],
          "samples-languages": [
            "shell"
          ]
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": false,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```