Skip to main content
POST
/
v1
/
card-tokenize
Tokenizar cartao
curl --request POST \
  --url https://api-payment.safefypay.com.br/v1/card-tokenize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cardNumber": "4111111111111111",
  "cardHolderName": "JOAO SILVA",
  "cardExpirationMonth": "12",
  "cardExpirationYear": "2028",
  "cardCvv": "123"
}
'
{
  "data": {
    "cardToken": "ct_abc123def456",
    "last4": "1111",
    "brand": "visa"
  },
  "message": "<string>",
  "error": {
    "message": "Token invalido ou expirado.",
    "code": "unauthorized"
  }
}
Tokenizes a credit card using the merchant’s active acquirer, without storing PAN/CVV in Safefy’s database. The returned token can be used in POST /v1/transactions via the cardToken field.

​
Request

POST /v1/card-tokenize 
{
  "cardNumber": "4111111111111111",
  "cardHolderName": "João Silva",
  "cardExpirationMonth": 12,
  "cardExpirationYear": 2028,
  "cardCvv": "123"
}

​
Parameters

FieldTypeRequiredDescription
cardNumberstringyesCard number (13-19 digits)
cardHolderNamestringyesName printed on the card
cardExpirationMonthintyesExpiration month (1-12)
cardExpirationYearintyesExpiration year (e.g. 2028)
cardCvvstringyesSecurity code (3-4 digits)

​
Responses

​
200 — Success

{
  "data": {
    "cardToken": "ct_abc123def456",
    "last4": "1111",
    "brand": "visa"
  }
}
FieldTypeDescription
cardTokenstringCard token (prefix ct_). Time-limited validity.
last4stringLast 4 digits of the card
brandstringCard brand (e.g. visa, mastercard)

​
400 — Invalid data

{
  "error": {
    "message": "Invalid card data.",
    "code": "invalid_card_data"
  }
}

​
401 — Invalid JWT token

{
  "error": {
    "message": "Invalid token.",
    "code": "invalid_token"
  }
}

​
422 — Acquirer doesn’t support tokenization

{
  "error": {
    "message": "Configured acquirer does not natively support tokenization.",
    "code": "tokenization_not_supported"
  }
}

Authorizations

​
Authorization
string
header
required

Token JWT obtido via /v1/auth/token

Body

application/json
​
cardNumber
string
required

Numero do cartao (13-19 digitos)

Example:

"4111111111111111"

​
cardHolderName
string
required

Nome impresso no cartao

Example:

"JOAO SILVA"

​
cardExpirationMonth
string
required

Mes de expiracao (1-12)

Example:

"12"

​
cardExpirationYear
string
required

Ano de expiracao (4 digitos)

Example:

"2028"

​
cardCvv
string
required

Codigo de seguranca (3-4 digitos)

Example:

"123"

Response

Cartao tokenizado com sucesso

​
data
object
​
message
string | null
​
error
object