• Português

API for Virtual Cards

This documentation describes the APIs required for the integration of the virtual card product. The APIs are organized into categories, with practical examples and detailed information for each endpoint.

---

Create a Virtual Card

[POST] /issuing-card

Creates a new virtual card associated with a cardholder.

Body params

Field name	Data type	Required	Description
holderName	string	Yes	Cardholder's name. Example: holderName="Tony Praag".
holderTaxId	string	Yes	Cardholder's CPF (11 digits) or CNPJ (14 digits). Example: holderTaxId="012.345.678-90".
holderExternalId	string	Yes	Unique ID to prevent duplicate holders. Example: holderExternalId="my-entity/123".
displayName	string	No	Card display name. Example: displayName="ANTHONY PRAAG".
rules	array	No	Spending rules for the card. List of dictionaries containing amount, currencyCode, interval, and name.
productId	string	No	Product ID to which the card is bound. Example: productId="538102".
tags	array	No	List of strings for tagging. Example: tags=["travel", "food"].
streetLine1	string	No	Cardholder's main address. Example: streetLine1="Av. Paulista, 200".
streetLine2	string	No	Cardholder's address complement. Example: streetLine2="Apto. 123".
district	string	No	Cardholder's district or neighborhood. Example: district="Bela Vista".
city	string	No	Cardholder's city. Example: city="Sao Paulo".
stateCode	string	No	Cardholder's state code. Example: stateCode="SP".
zipCode	string	No	Cardholder's zip code. Example: zipCode="01311-200".
expand	array	No	Fields to expand. Options: rules, security_code, number, expiration.

Request Example

curl --request POST \
  --url "/issuing-card" \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "holderName": "Tony Praag",
    "holderTaxId": "012.345.678-90",
    "holderExternalId": "my-entity/123",
    "displayName": "ANTHONY PRAAG",
    "rules": [
      {
        "amount": 90000,
        "currencyCode": "BRL",
        "interval": "weekly",
        "name": "weekly_limit"
      }
    ],
    "tags": ["travel", "food"]
  }'

Responses

200 - Success

{
  "product_id": 53810203,
  "city": "Sao Paulo",
  "created": "2022-05-24T14:27:15.989740",
  "display_name": "ANTHONY PRAAG",
  "district": "Bela Vista",
  "expiration": "2029-04-30T23:59:59.999999+00:00",
  "holder_external_id": "my-entity/123",
  "holder_id": "4843929958612992",
  "holder_name": "Tony Praag",
  "holder_tax_id": "012.345.678-90",
  "id": "5189831499972608",
  "number": "5381 0203 3678 0289",
  "rules": [
    {
      "amount": 900000,
      "categories": [],
      "counter_amount": 0,
      "countries": [],
      "currency_code": "BRL",
      "currency_name": "Brazilian Real",
      "currency_symbol": "R$",
      "id": "6315731406815232",
      "interval": "week",
      "methods": [],
      "name": "Example Rule"
    }
  ],
  "security_code": "719",
  "state_code": "SP",
  "status": "active",
  "street_line_1": "Av. Paulista, 200",
  "street_line_2": "Apto. 123",
  "tags": ["travel", "food"],
  "type": "virtual",
  "updated": "2022-05-24T14:27:16.014839",
  "zip_code": "01311-200"
}

422 - Unprocessable

{
  "error": {
    "message": {
      "base": ["Invalid parameters"]
    },
    "status": 422
  }
}

---

List Virtual Cards

[GET] /issuing-card

Lists all issued virtual cards.

Query params

Field name	Data type	Required	Description
cursor	string	No	String to get the next batch of results.
limit	int	No	Maximum number of cards to retrieve. Max = 100.
after	date	No	Filter for cards created after a specific date. Example: "2022-01-20".
before	date	No	Filter for cards created before a specific date. Example: "2022-02-20".
status	array	No	List of statuses. Options: "created", "pending", "active", "blocked", "canceled", "expired".
ids	array	No	List of IDs to filter cards.
types	array	No	Filter by card types. Options: "physical", "virtual".
holderIds	array	No	Filter by cardholder IDs. Example: holderIds=["5656565656565656"].
tags	array	No	Filter by tags. Example: tags=["tony", "praag"].
expand	array	No	Fields to expand. Options: rules, securityCode, number, expiration.

Request Example

curl --request GET \
  --url "/issuing-card?status=active&limit=10" \
  --header 'Authorization: Bearer {token}'

Responses

200 - Success

[
  {
    "product_id": 53810203,
    "city": "Sao Paulo",
    "created": "2022-05-24T14:27:15.989740",
    "display_name": "ANTHONY PRAAG",
    "district": "Bela Vista",
    "expiration": "2029-04-30T23:59:59.999999+00:00",
    "holder_external_id": "my-entity/123",
    "holder_id": "4843929958612992",
    "holder_name": "Tony Praag",
    "holder_tax_id": "012.345.678-90",
    "id": "5189831499972608",
    "number": "5381 0203 3678 0289",
    "rules": [
      {
        "amount": 900000,
        "categories": [],
        "counter_amount": 0,
        "countries": [],
        "currency_code": "BRL",
        "currency_name": "Brazilian Real",
        "currency_symbol": "R$",
        "id": "6315731406815232",
        "interval": "week",
        "methods": [],
        "name": "Example Rule"
      }
    ],
    "security_code": "719",
    "state_code": "SP",
    "status": "active",
    "street_line_1": "Av. Paulista, 200",
    "street_line_2": "Apto. 123",
    "tags": ["travel", "food"],
    "type": "virtual",
    "updated": "2022-05-24T14:27:16.014839",
    "zip_code": "01311-200"
  }
]

---

Get a Virtual Card by ID

[GET] /issuing-card/:id

Retrieves details of a specific virtual card.

Query params

Field name	Data type	Required	Description
id	string	Yes	Unique ID of the desired virtual card.
expand	array	No	Fields to expand. Options: rules, securityCode, number, expiration.

Request Example

curl --request GET \
  --url "/issuing-card/card_abcdef123456" \
  --header 'Authorization: Bearer {token}'

Responses

200 - Success

{
  "product_id": 53810203,
  "city": "Sao Paulo",
  "created": "2022-05-24T14:27:15.989740",
  "display_name": "ANTHONY PRAAG",
  "district": "Bela Vista",
  "expiration": "2029-04-30T23:59:59.999999+00:00",
  "holder_external_id": "my-entity/123",
  "holder_id": "4843929958612992",
  "holder_name": "Tony Praag",
  "holder_tax_id": "012.345.678-90",
  "id": "5189831499972608",
  "number": "5381 0203 3678 0289",
  "rules": [
    {
      "amount": 900000,
      "categories": [],
      "counter_amount": 0,
      "countries": [],
      "currency_code": "BRL",
      "currency_name": "Brazilian Real",
      "currency_symbol": "R$",
      "id": "6315731406815232",
      "interval": "week",
      "methods": [],
      "name": "Example Rule"
    }
  ],
  "security_code": "719",
  "state_code": "SP",
  "status": "active",
  "street_line_1": "Av. Paulista, 200",
  "street_line_2": "Apto. 123",
  "tags": ["travel", "food"],
  "type": "virtual",
  "updated": "2022-05-24T14:27:16.014839",
  "zip_code": "01311-200"
}

---

Patch a Virtual Card

[PATCH] /issuing-card/:id

Updates details of a virtual card.

Body params

Field name	Data type	Required	Description
id	string	Yes	ID of the virtual card to update.
status	string	No	Updates the card's status. Options: blocked, active.
displayName	string	No	Updates the card display name.
rules	array	No	Updates spending rules.
tags	array	No	Updates the tags associated with the card.

Request Example

curl --request PATCH \
  --url "/issuing-card/card_abcdef123456" \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "blocked",
    "rules": [
      { "category": "travel", "amount": 2000 }
    ]
  }'

Responses

200 - Success

{
  "product_id": 53810203,
  "city": "Sao Paulo",
  "created": "2022-05-24T14:27:15.989740",
  "display_name": "ANTHONY PRAAG",
  "district": "Bela Vista",
  "expiration": "2029-04-30T23:59:59.999999+00:00",
  "holder_external_id": "my-entity/123",
  "holder_id": "4843929958612992",
  "holder_name": "Tony Praag",
  "holder_tax_id": "012.345.678-90",
  "id": "5189831499972608",
  "number": "5381 0203 3678 0289",
  "rules": [
    {
      "amount": 900000,
      "categories": [],
      "counter_amount": 0,
      "countries": [],
      "currency_code": "BRL",
      "currency_name": "Brazilian Real",
      "currency_symbol": "R$",
      "id": "6315731406815232",
      "interval": "week",
      "methods": [],
      "name": "Example Rule"
    }
  ],
  "security_code": "719",
  "state_code": "SP",
  "status": "blocked",
  "street_line_1": "Av. Paulista, 200",
  "street_line_2": "Apto. 123",
  "tags": ["travel", "food"],
  "type": "virtual",
  "updated": "2022-05-24T14:27:16.014839",
  "zip_code": "01311-200"
}

---

Cancel a Virtual Card

[DELETE] /issuing-card/:id

Cancels a specific virtual card.

Query params

Field name	Data type	Required	Description
id	string	Yes	ID of the virtual card to cancel.

Request Example

curl --request DELETE \
  --url "/issuing-card/card_abcdef123456" \
  --header 'Authorization: Bearer {token}'

Responses

200 - Success

{
  "product_id": 53810203,
  "city": "Sao Paulo",
  "created": "2022-05-24T14:27:15.989740",
  "display_name": "ANTHONY PRAAG",
  "district": "Bela Vista",
  "expiration": "2029-04-30T23:59:59.999999+00:00",
  "holder_external_id": "my-entity/123",
  "holder_id": "4843929958612992",
  "holder_name": "Tony Praag",
  "holder_tax_id": "012.345.678-90",
  "id": "5189831499972608",
  "number": "5381 0203 3678 0289",
  "rules": [
    {
      "amount": 900000,
      "categories": [],
      "counter_amount": 0,
      "countries": [],
      "currency_code": "BRL",
      "currency_name": "Brazilian Real",
      "currency_symbol": "R$",
      "id": "6315731406815232",
      "interval": "week",
      "methods": [],
      "name": "Example Rule"
    }
  ],
  "security_code": "719",
  "state_code": "SP",
  "status": "deleted",
  "street_line_1": "Av. Paulista, 200",
  "street_line_2": "Apto. 123",
  "tags": ["travel", "food"],
  "type": "virtual",
  "updated": "2022-05-24T14:27:16.014839",
  "zip_code": "01311-200"
}

---

List Virtual Card Logs

[GET] /issuing-card/log

Lists logs of operations performed on virtual cards.

Query params

Field name	Data type	Required	Description
cursor	string	No	String to get the next batch of results.
ids	array	No	List of log IDs to filter.
limit	int	No	Maximum number of logs to retrieve. Max = 100.
after	date	No	Filter for logs created after a specific date. Example: "2022-01-20".
before	date	No	Filter for logs created before a specific date. Example: "2022-02-20".
types	array	No	Filter logs by type. Options: "blocked", "canceled", "created", "expired", "unblocked", "updated".
cardIds	array	No	List of card IDs to filter logs.

Request Example

curl --request GET \
  --url "/issuing-card/log?limit=10" \
  --header 'Authorization: Bearer {token}'

Responses

200 - Success

[
  {
    "card": {
      "product_id": 53810203,
      "city": "Sao Paulo",
      "created": "2022-05-24T13:20:04.414204",
      "display_name": "ANTHONY PRAAG",
      "district": "Bela Vista",
      "expiration": "****-**-**T**:**:**.******+00:00",
      "holder_external_id": "my-entity/123",
      "holder_id": "4843929958612992",
      "holder_name": "Tony Praag",
      "holder_tax_id": "012.345.678-90",
      "id": "5764233648144384",
      "number": "**** **** **** 8212",
      "rules": [
        {
          "amount": 900000,
          "categories": null,
          "counter_amount": null,
          "countries": null,
          "currency_code": "BRL",
          "currency_name": null,
          "currency_symbol": null,
          "id": "5201283694723072",
          "interval": "week",
          "methods": null,
          "name": "Example Rule"
        }
      ],
      "security_code": "***",
      "state_code": "SP",
      "status": "active",
      "street_line_1": "Av. Paulista, 200",
      "street_line_2": "Apto. 123",
      "tags": ["travel", "food"],
      "type": "virtual",
      "updated": "2022-05-24T13:43:30.730126",
      "zip_code": "01311-200"
    },
    "created": "2022-05-24T13:20:04.471466",
    "id": "6327183601565696",
    "type": "created"
  }
]

---

Get a Virtual Card Log by ID

[GET] /issuing-card/log/:id

Retrieves details of a specific virtual card log.

Query params

Field name	Data type	Required	Description
id	string	Yes	ID of the desired log.

Request Example

curl --request GET \
  --url "/issuing-card/log/log_12345" \
  --header 'Authorization: Bearer {token}'

Responses

200 - Success

{
  "card": {
    "product_id": 53810203,
    "city": "Sao Paulo",
    "created": "2022-05-24T13:20:04.414204",
    "display_name": "ANTHONY PRAAG",
    "district": "Bela Vista",
    "expiration": "****-**-**T**:**:**.******+00:00",
    "holder_external_id": "my-entity/123",
    "holder_id": "4843929958612992",
    "holder_name": "Tony Praag",
    "holder_tax_id": "012.345.678-90",
    "id": "5764233648144384",
    "number": "**** **** **** 8212",
    "rules": [
      {
        "amount": 900000,
        "categories": null,
        "counter_amount": null,
        "countries": null,
        "currency_code": "BRL",
        "currency_name": null,
        "currency_symbol": null,
        "id": "5201283694723072",
        "interval": "week",
        "methods": null,
        "name": "Example Rule"
      }
    ],
    "security_code": "***",
    "state_code": "SP",
    "status": "active",
    "street_line_1": "Av. Paulista, 200",
    "street_line_2": "Apto. 123",
    "tags": ["travel", "food"],
    "type": "virtual",
    "updated": "2022-05-24T13:43:30.730126",
    "zip_code": "01311-200"
  },
  "created": "2022-05-24T13:20:04.471466",
  "id": "6327183601565696",
  "type": "created"
}

---