Cards API
The Cards API allows you to manage payment cards in your BillOver account.
Contents
Base URL
https://api.billover.com/v1/cards/
Field Definitions
Common Fields
| Field | Type | Description | Required |
|---|---|---|---|
| uid | UUID | Unique identifier for the card | Read-only |
| hf_id | string | Human-friendly ID | Read-only |
| first_four_digits | string | First four digits of the card number | No |
| last_four_digits | string | Last four digits of the card number | No |
| created_at | datetime | Creation date | Read-only |
| permissions | object | User permissions for this card | Read-only |
List Cards
Retrieve a list of all cards.
GET /v1/cards/
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| query | string | Search in first four digits, last four digits, and human-friendly ID |
Response
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"hf_id": "ABC",
"uid": "67df8b92-ed61-4796-b5c2-9505bf9d4b6a",
"first_four_digits": "4111",
"last_four_digits": "1111",
"created_at": "2024-01-30T12:00:00Z",
"permissions": {
"can_update": true,
"can_delete": true
}
},
{
"hf_id": "XYZ",
"uid": "89ef0123-4567-89ab-cdef-0123456789ab",
"first_four_digits": "5555",
"last_four_digits": "4444",
"created_at": "2024-01-29T12:00:00Z",
"permissions": {
"can_update": true,
"can_delete": true
}
}
]
}
Get Card
Retrieve a specific card by ID.
GET /v1/cards/{uid}
Response
{
"hf_id": "ABC",
"uid": "67df8b92-ed61-4796-b5c2-9505bf9d4b6a",
"first_four_digits": "4111",
"last_four_digits": "1111",
"created_at": "2024-01-30T12:00:00Z",
"permissions": {
"can_update": true,
"can_delete": true
}
}
Create Card
Create a new card. If a card with the same first and last four digits exists, it will return the existing card.
POST /v1/cards/
Request Body
{
"first_four_digits": "4111",
"last_four_digits": "1111"
}
Response
{
"hf_id": "ABC",
"uid": "67df8b92-ed61-4796-b5c2-9505bf9d4b6a",
"first_four_digits": "4111",
"last_four_digits": "1111",
"created_at": "2024-01-30T12:00:00Z"
}
Update Card
Update an existing card.
PUT /v1/cards/{uid}
Request Body
{
"first_four_digits": "5555",
"last_four_digits": "4444"
}
Response
{
"hf_id": "ABC",
"uid": "67df8b92-ed61-4796-b5c2-9505bf9d4b6a",
"first_four_digits": "5555",
"last_four_digits": "4444",
"created_at": "2024-01-30T12:00:00Z"
}
Delete Card
Delete an existing card.
DELETE /v1/cards/{uid}
Response
HTTP/1.1 204 No Content
Example Usage
List Cards
curl -X GET \
'https://api.billover.com/v1/cards/?query=4111' \
-H 'Api-Key: YOUR_API_KEY'
Get Card
curl -X GET \
https://api.billover.com/v1/cards/67df8b92-ed61-4796-b5c2-9505bf9d4b6a \
-H 'Api-Key: YOUR_API_KEY'
Create a Card
curl -X POST \
https://api.billover.com/v1/cards/ \
-H 'Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"first_four_digits": "4111",
"last_four_digits": "1111"
}'
Update a Card
curl -X PUT \
https://api.billover.com/v1/cards/67df8b92-ed61-4796-b5c2-9505bf9d4b6a \
-H 'Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"first_four_digits": "5555",
"last_four_digits": "4444"
}'
Delete a Card
curl -X DELETE \
https://api.billover.com/v1/cards/67df8b92-ed61-4796-b5c2-9505bf9d4b6a \
-H 'Api-Key: YOUR_API_KEY'