Skip to main content
POST
/
v1
/
cards
Register a card
curl --request POST \
  --url https://api-global.fastpaybrasil.com/v1/cards \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerId": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "number": "4111111111111111",
  "holderName": "JOHN DOE",
  "expirationMonth": "12",
  "expirationYear": "2028",
  "cvv": "123",
  "alias": "My Visa Card",
  "validateCard": true
}
'
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
  "token": "tok_abc123xyz",
  "maskedNumber": "****1111",
  "status": "pending_validation",
  "pendingActivation": true,
  "activation": {
    "required": true,
    "message": "Verifique o valor da transacao de teste na fatura do cartao e use o endpoint /cards/:id/activate"
  }
}

Authorizations

​
Authorization
string
header
required

HTTP Basic authentication. Use your secret key as the username and an empty string as password. The API key should be base64 encoded in the format 'username:' when sending the Authorization header.

Body

application/json
​
customerId
string
required

Customer ID who owns the card

Example:

"2RhQg9M7ZCg3X3nMb9W1kX8Q"

​
number
string
required

Card number

Example:

"4111111111111111"

​
holderName
string
required

Name printed on card

Example:

"JOHN DOE"

​
expirationMonth
string
required

Expiration month (01-12)

Required string length: 2
Example:

"12"

​
expirationYear
string
required

Expiration year (YYYY)

Required string length: 4
Example:

"2028"

​
cvv
string
required

Security code

Minimum string length: 3
Example:

"123"

​
alias
string

Optional alias for the card

Example:

"My Visa Card"

​
validateCard
boolean
default:true

Whether to validate the card with a test transaction. When true, a small amount (up to R$ 2.00) is charged and must be confirmed via the /cards/{id}/activate endpoint.

Example:

true

Response

Card registered successfully

​
id
string

Card token ID

Example:

"2RhQg9M7ZCg3X3nMb9W1kX8Q"

​
token
string

Card token for future reference

Example:

"tok_abc123xyz"

​
maskedNumber
string | null

Masked card number (last 4 digits)

Example:

"****1111"

​
status
enum<string>

Card status

Available options:
pending_validation,
active
Example:

"pending_validation"

​
pendingActivation
boolean

Whether card requires activation

Example:

true

​
activation
object

Activation instructions (only when validateCard=true)