GiveCard

https://givecard.readme.io
Admin
GiveCard is a 1:many payments platform that enables businesses to easily disburse funds at scale via...
Tokens:183,405
Snippets:681
Trust Score:9.9
Update:10 months ago
Show doc for...
Tokens:
Raw
### Get Programs

Source: https://givecard.readme.io/reference/quickstart

Retrieves a list of available programs for superbusinesses. This is necessary to obtain a program ID if you are designated as a superbusiness.

```APIDOC
## GET /api/v1/business/programs

### Description
Retrieves a list of available programs for superbusinesses.

### Method
GET

### Endpoint
/api/v1/business/programs

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl --request GET \
  --url <https://api.dev.givecard.dev/api/v1/business/programs> \
  --header 'authorization: Bearer {superbusinessAPIKey}'
```

### Response
#### Success Response (200)
* **programs** (array) - A list of program objects.

#### Response Example
```json
{
  "programs": [
    {
      "programId": "{programId}",
      "name": "Example Program"
    }
  ]
}
```
```

--------------------------------

### Order and Ship Card

Source: https://givecard.readme.io/reference/quickstart

Orders a physical card and ships it to a specified address. Requires card count and shipping details.

```APIDOC
## POST /api/v1/cards/orderAndShip

### Description
Orders a physical card and ships it to a specified address. Requires card count and shipping details.

### Method
POST

### Endpoint
/api/v1/cards/orderAndShip

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **shipmentMethod** (string) - Required - The shipping method (e.g., "USPS_PRIORITY").
- **shippingAddress** (object) - Required - The shipping address details.
  - **city** (string) - Required - The city for shipping.
  - **country** (string) - Required - The country for shipping.
  - **firstName** (string) - Required - The first name for shipping.
  - **lastName** (string) - Required - The last name for shipping.
  - **postalCode** (string) - Required - The postal code for shipping.
  - **state** (string) - Required - The state for shipping.
  - **street** (string) - Required - The street address.
- **cardCount** (integer) - Required - The number of cards to order.

### Request Example
```json
{
  "shipmentMethod": "USPS_PRIORITY",
  "shippingAddress": {
    "city": "Boston",
    "country": "USA",
    "firstName": "Ada",
    "lastName": "Lovelace",
    "postalCode": "02110",
    "state": "MA",
    "street": "1 Hard Drive"
  },
  "cardCount": 1
}
```

### Response
#### Success Response (200)
* **cardIds** (array) - A list of card IDs that were ordered.

#### Response Example
```json
{
  "cardIds": [
    "{uuid}"
  ]
}
```
```

--------------------------------

### cURL GET Request Example

Source: https://givecard.readme.io/reference/autopayouts

This snippet demonstrates how to make a GET request to the Givecard API using cURL. It includes the necessary URL and headers for the request.

```shell
curl --request GET \
     --url https://api.dev.givecard.dev/api/v1/autopayouts \
     --header 'accept: */*'
```

--------------------------------

### Load Card

Source: https://givecard.readme.io/reference/quickstart

Loads a specified amount onto a card using its ID or external ID.

```APIDOC
## POST /api/v1/cards/load

### Description
Loads a specified amount onto a card using its ID or external ID.

### Method
POST

### Endpoint
/api/v1/cards/load

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **cardIds** (array) - Required - A list of card IDs to load funds onto.
  - **uuid** (string) - Required - The unique identifier for the card.
- **amount** (string) - Required - The amount to load onto the card (e.g., "10.10").

### Request Example
```json
{
  "cardIds": [
    "{uuid}"
  ],
  "amount": "10.10"
}
```

### Response
#### Success Response (200)
* **status** (string) - The status of the loading operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Order and Ship a Card using cURL

Source: https://givecard.readme.io/reference/quickstart

Orders a physical card and initiates shipping. This endpoint requires an API key for authorization and accepts shipment details and card count as JSON payload. The response contains details of the ordered card, including its ID.

```shell
curl --request POST \
--url <https://api.dev.givecard.dev/api/v1/cards/orderAndShip> \
--header 'accept: _/_' \
--header 'authorization: {key}' \
--header 'content-type: application/json' \
--data '{
"shipmentMethod": "USPS_PRIORITY",
"shippingAddress": {
"city": "Boston",
"country": "USA",
"firstName": "Ada",
"lastName": "Lovelace",
"postalCode": "02110",
"state": "MA",
"street": "1 Hard Drive"
},
"cardCount": 1,
}'
```

--------------------------------

### Load Funds onto a Card using cURL

Source: https://givecard.readme.io/reference/quickstart

Loads funds onto a previously ordered card. This endpoint requires an API key for authorization and accepts the card ID and the amount to be loaded as a JSON payload. The card ID can be obtained from the OrderAndShipCards response.

```shell
curl --request POST \
--url <https://api.dev.givecard.dev/api/v1/cards/load> \
--header 'accept: _/_' \
--header 'authorization: {key}' \
--header 'content-type: application/json' \
--data '{
"cardIds": [
{"uuid"}
],
"amount": "10.10"
}'
```

--------------------------------

### cURL Request to Get Webhooks Access Link

Source: https://givecard.readme.io/reference/webhooks-1

This example demonstrates how to make a GET request to the /api/v1/business/webhooks/accessLink endpoint using cURL. It specifies the request method, URL, and an 'accept' header.

```shell
curl --request GET \
     --url https://api.dev.givecard.dev/api/v1/business/webhooks/accessLink \
     --header 'accept: */*'
```

--------------------------------

### cURL GET Request to Retrieve Card Spend Rules

Source: https://givecard.readme.io/reference/spendrules

Example cURL command to perform a GET request to the Givecard API to fetch card spend rules. This command includes the necessary URL and headers for authentication and content negotiation.

```shell
curl --request GET \
     --url https://api.dev.givecard.dev/api/v1/cards/cardId/spendRules \
     --header 'accept: */*'
```

--------------------------------

### Ruby Example for Givecard API Authentication Test

Source: https://givecard.readme.io/reference/auth

This Ruby code snippet demonstrates how to test the Givecard API authentication using the Net::HTTP library. It sends a GET request to the base URL and logs the status code and response body. Proper authentication headers should be included for a successful request.

```ruby
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse('https://api.dev.givecard.dev/api/v1')

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true # For HTTPS

request = Net::HTTP::Get.new(uri.request_uri)
request['accept'] = '*/*'
# Add your authentication headers here, e.g.:
# request['Authorization'] = 'Bearer YOUR_API_KEY'

response = http.request(request)

puts "Status Code: #{response.code}"
puts "Response Body: #{response.body}"

if response.code == '200'
  puts "Authentication successful!"
else
  puts "Authentication failed."
end
```

--------------------------------

### cURL GET Request for Funding Account Balance

Source: https://givecard.readme.io/reference/fundingaccount

This snippet demonstrates how to make a GET request to retrieve the funding account balance using cURL. It includes the necessary URL and headers for the request.

```shell
curl --request GET \
     --url https://api.dev.givecard.dev/api/v1/business/fundingAccount/balance \
     --header 'accept: */*'
```

--------------------------------

### Get GiveCard Program ID using cURL

Source: https://givecard.readme.io/reference/quickstart

Retrieves the program ID necessary for superbusinesses to order cards. This endpoint requires a superbusiness API key for authorization. It returns program details, including the program ID.

```shell
curl --request GET \
--url <https://api.dev.givecard.dev/api/v1/business/programs> \
--header 'authorization: Bearer {superbusinessAPIKey}'
```

--------------------------------

### Node.js Example for Givecard API Authentication Test

Source: https://givecard.readme.io/reference/auth

This Node.js code snippet shows how to test the Givecard API authentication by making a GET request to the base URL. It includes handling for both successful (200) and error (401) responses. Ensure you install the 'axios' package for making HTTP requests.

```javascript
const axios = require('axios');

const apiUrl = 'https://api.dev.givecard.dev/api/v1';

async function testAuth() {
  try {
    const response = await axios.get(apiUrl, {
      headers: {
        'accept': '*/*'
        // Add your authentication headers here, e.g.:
        // 'Authorization': 'Bearer YOUR_API_KEY'
      }
    });
    console.log('Success:', response.status);
    console.log('Response Body:', response.data);
  } catch (error) {
    if (error.response) {
      console.error('Error:', error.response.status);
      console.error('Error Response Body:', error.response.data);
    } else if (error.request) {
      console.error('No response received:', error.request);
    } else {
      console.error('Error setting up request:', error.message);
    }
  }
}

testAuth();
```

--------------------------------

### POST /api/v1/business/simulateFundingAccountDeposit

Source: https://givecard.readme.io/reference/simulatefundingaccountdepositv1

Sandbox Only: Simulates a funding account deposit to load cards in the sandbox environment. The amount is specified in dollars.

```APIDOC
## POST /api/v1/business/simulateFundingAccountDeposit

### Description
Sandbox Only: Simulates a funding account deposit. This simulated money is used to load cards in the sandbox environment. Amount is in dollars, e.g. set amount to 10000 to add $10,000 or 11.50 to add $11.50.

### Method
POST

### Endpoint
https://api.dev.givecard.dev/api/v1/business/simulateFundingAccountDeposit

### Parameters
#### Header Parameters
- **Idempotency-Key** (string) - Required - Unique key to ensure idempotency of the request.

#### Query Parameters
- **programId** (string) - Optional - Program ID is only required for superbusinesses.

#### Request Body
- **accountType** (string) - Optional - Account Type is only necessary for superbusinesses that have multiple funding accounts. If there are multiple funding accounts for the superbusiness and no account type is given, it will default to returning to the funding account with type 'card'. Enum: `card`, `bank_transfer`, `on_demand_card`.
- **amount** (number) - Required - The amount to deposit in dollars.

### Request Example
```json
{
  "accountType": "card",
  "amount": 10000
}
```

### Response
#### Success Response (200)
This endpoint returns an empty response upon successful simulation.

#### Response Example
(No content)
```

--------------------------------

### POST /websites/givecard_readme_io/programs

Source: https://givecard.readme.io/reference/createprogramv1

Creates a new program for a superbusiness. Programs have their own funding accounts, allowing a business to separate funds. If you haven't been designated as a superbusiness, this endpoint will return a 400 Bad Request status.

```APIDOC
## POST /websites/givecard_readme_io/programs

### Description
Creates a new program for a superbusiness. Programs have their own funding accounts, allowing a business to separate funds. For further info, refer to Getting Started in the docs.
If you haven't been designated as a superbusiness, this endpoint will return a 400 Bad Request status.

### Method
POST

### Endpoint
/websites/givecard_readme_io/programs

### Parameters
#### Request Body
- **name** (string) - Required - The name of the program.
- **funding_account_id** (string) - Required - The ID of the funding account for the program.

### Request Example
```json
{
  "name": "Summer Charity Drive",
  "funding_account_id": "acc_12345"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the created program.
- **name** (string) - The name of the program.
- **funding_account_id** (string) - The ID of the funding account associated with the program.
- **created_at** (string) - The timestamp when the program was created.

#### Response Example
```json
{
  "id": "prog_abcdef123456",
  "name": "Summer Charity Drive",
  "funding_account_id": "acc_12345",
  "created_at": "2023-10-27T10:00:00Z"
}
```

#### Error Response (400 Bad Request)
- **error** (string) - Description of the error. Example: "Superbusiness designation required."
```

--------------------------------

### Get Spend Rules On Card

Source: https://givecard.readme.io/reference/getspendrulesoncardv1

Retrieves all the relevant spend rules that could affect a card for a given transaction. For details on rule interaction, refer to the Spend Rules guide.

```APIDOC
## GET /websites/givecard_readme_io/spend_rules

### Description
Returns all the relevant spend rules that could affect a card for a given transaction. To understand how these rules interact with one another, please visit the Spend Rules guide at the top of our documentation.

### Method
GET

### Endpoint
/websites/givecard_readme_io/spend_rules

### Parameters
#### Query Parameters
- **transaction_id** (string) - Required - The ID of the transaction for which to retrieve spend rules.
- **card_id** (string) - Required - The ID of the card for which to retrieve spend rules.

### Response
#### Success Response (200)
- **spend_rules** (array) - A list of spend rules affecting the card for the transaction.
  - **rule_id** (string) - The unique identifier for the spend rule.
  - **rule_name** (string) - The name of the spend rule.
  - **rule_type** (string) - The type of the spend rule (e.g., "category", "amount_limit").
  - **details** (object) - Specific details of the rule.

#### Response Example
```json
{
  "spend_rules": [
    {
      "rule_id": "sr_12345",
      "rule_name": "Groceries Limit",
      "rule_type": "amount_limit",
      "details": {
        "limit_amount": 500,
        "currency": "USD"
      }
    },
    {
      "rule_id": "sr_67890",
      "rule_name": "No Online Purchases",
      "rule_type": "merchant_category",
      "details": {
        "excluded_categories": ["online_retail"]
      }
    }
  ]
}
```
```

--------------------------------

### POST /api/v1/business/program

Source: https://givecard.readme.io/reference/superbusiness

This endpoint is used to create a new business program. It requires a JSON request body and returns a success or error response based on the request's validity.

```APIDOC
## POST /api/v1/business/program

### Description
Creates a new business program.

### Method
POST

### Endpoint
/api/v1/business/program

### Parameters
#### Query Parameters
None

#### Request Body
(Object) - The request body should contain the details for the new business program.

### Request Example
```json
{
  "program_details": "..."
}
```

### Response
#### Success Response (200)
(Object) - Details of the newly created business program.

#### Error Responses
- **400 Bad Request**: Indicates a client-side error in the request.
- **404 Not Found**: Indicates that the requested resource was not found.
- **409 Conflict**: Indicates a conflict with the current state of the resource.
- **500 Internal Server Error**: Indicates an error on the server side.

#### Response Example (409 Conflict)
```json
{
  "badRequest": {
    "fieldViolations": [
      {
        "description": "A description of why the request element is bad.",
        "field": "fieldViolations.field",
        "code": 123
      }
    ],
    "errorInfo": {
      "Reason": "OUTDATED_VERSION",
      "metadata": {},
      "fieldErrors": {
        "localizedMessage": {
          "locale": "en-US",
          "message": "The localized error message."
        },
        "msg": "required"
      }
    },
    "requestInfo": {
      "requestID": "some-request-id",
      "servingData": "any-serving-data"
    }
  }
}
```

#### Response Example (500 Internal Server Error)
```json
{
  "badRequest": {
    "fieldViolations": [
      {
        "description": "A description of why the request element is bad.",
        "field": "fieldViolations.field",
        "code": 123
      }
    ],
    "errorInfo": {
      "Reason": "UNKNOWN",
      "metadata": {},
      "fieldErrors": {
        "localizedMessage": {
          "locale": "en-US",
          "message": "The localized error message."
        },
        "msg": "required"
      }
    },
    "requestInfo": {
      "requestID": "some-request-id",
      "servingData": "any-serving-data"
    }
  }
}
```
```

--------------------------------

### GET /api/v1/cards/{cardId}/spendRules

Source: https://givecard.readme.io/reference/getspendrulesoncardv1

Retrieves all spend rules that apply to a given card, which can affect transactions. It's recommended to consult the Spend Rules guide for details on how these rules interact.

```APIDOC
## GET /api/v1/cards/{cardId}/spendRules

### Description
Returns all the relevant spend rules that could affect a card for a given transaction. To understand how these rules interact with one another, please visit the Spend Rules guide at the top of our documentation.

### Method
GET

### Endpoint
https://api.dev.givecard.dev/api/v1/cards/{cardId}/spendRules

### Parameters
#### Path Parameters
- **cardId** (string) - Required - The unique identifier of the card.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **merchantRules** (array) - MerchantRules are deprecated, please refer to the SpendRules array instead.
- **spendRules** (array) - An array of spend rule objects applicable to the card.

#### Response Example
```json
{
  "merchantRules": [
    {
      "businessId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "createdAt": "2023-10-27T10:00:00Z",
      "id": "f0e9d8c7-b6a5-4321-0987-fedcba012345",
      "merchantCategories": ["5814", "5999"],
      "mode": "block",
      "name": "Office Supplies",
      "scope": "GLOBAL"
    }
  ],
  "spendRules": [
    {
      "allowCategories": [],
      "blockCategories": ["5814", "5999"],
      "businessId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "createdAt": "2023-10-27T10:00:00Z",
      "description": "Block office supply purchases",
      "endDate": null,
      "id": "c1d2e3f4-a5b6-7890-1234-567890abcdef",
      "locationId": null,
      "mode": "block",
      "name": "Office Supply Block",
      "startDate": null,
      "transactionType": "purchase"
    }
  ]
}
```

#### Error Response (400, 404, 500)
- **error** (object) - Contains details about the error.
  - **code** (string) - Error code.
  - **message** (string) - Error message.
  - **status** (integer) - HTTP status code.

#### Error Response Example
```json
{
  "error": {
    "code": "INVALID_CARD_ID",
    "message": "The provided card ID is invalid.",
    "status": 400
  }
}
```
```

--------------------------------

### POST /api/v1/business/program

Source: https://givecard.readme.io/reference/superbusiness

Creates a new program for a superbusiness. Programs have their own funding accounts, allowing a business to separate funds.

```APIDOC
## POST /api/v1/business/program

### Description
Creates a new program for a superbusiness. Programs have their own funding accounts, allowing a business to separate funds. For further information, refer to Getting Started in the docs.

If you haven't been designated as a superbusiness, this endpoint will return a 400 Bad Request status.

### Method
POST

### Endpoint
https://api.dev.givecard.dev/api/v1/business/program

### Parameters
#### Request Body
- **name** (string) - Required - The program's name.
- **productType** (string) - Required - Enum: `cards`, `bank_transfers`, `on_demand_cards`. Specifies the type of product for the program.
- **logoUrl** (string) - Optional - Logo URL for the program, displayed on the GiveCard admin dashboard.

### Request Example
```json
{
  "name": "Example Program",
  "productType": "cards",
  "logoUrl": "http://example.com/logo.png"
}
```

### Response
#### Success Response (200)
- **program** (object)
  - **id** (uuid) - The unique identifier for the program.
  - **name** (string) - The name of the program.
  - **productType** (string) - The type of product for the program.
  - **createdAt** (date-time) - The date and time the program was created.

#### Response Example (200)
```json
{
  "program": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "name": "Example Program",
    "productType": "cards",
    "createdAt": "2023-10-27T10:00:00Z"
  }
}
```

#### Error Response (400)
- **badRequest** (object)
  - **fieldViolations** (array of objects)
    - **field** (string) - The path to the violating field.
    - **description** (string) - A description of why the field is invalid.
    - **code** (int64)
  - **errorInfo** (object)
    - **Metadata** (object)
    - **Reason** (string) - Enum: `UNKNOWN`, `OUTDATED_VERSION`.
  - **fieldErrors** (object)
    - **localizedMessage** (object)
      - **locale** (string) - The locale of the message.
      - **message** (string) - The localized error message.
  - **requestInfo** (object)
    - **requestID** (string) - The unique request identifier.
    - **servingData** (string) - Any data used to serve the request.

#### Response Example (400)
```json
{
  "badRequest": {
    "fieldViolations": [
      {
        "field": "name",
        "description": "Name is a required field.",
        "code": 12345
      }
    ],
    "errorInfo": {
      "Metadata": {},
      "Reason": "UNKNOWN"
    },
    "fieldErrors": {
      "localizedMessage": {
        "locale": "en-US",
        "message": "Invalid request parameters."
      }
    },
    "requestInfo": {
      "requestID": "req-xyz789",
      "servingData": "encrypted-data"
    }
  }
}
```

#### Response Example (404)
```json
{
  "badRequest": {
    "fieldViolations": [
      {
        "field": "businessId",
        "description": "Superbusiness not found.",
        "code": 67890
      }
    ],
    "errorInfo": {
      "Metadata": {},
      "Reason": "UNKNOWN"
    },
    "fieldErrors": {
      "localizedMessage": {
        "locale": "en-US",
        "message": "Resource not found."
      }
    },
    "requestInfo": {
      "requestID": "req-abc123",
      "servingData": "encrypted-data"
    }
  }
}
```
```

--------------------------------

### POST /api/v1/business/program

Source: https://givecard.readme.io/reference/createprogramv1

Creates a new program for a superbusiness. Programs allow for separated funding accounts within a business. If not designated as a superbusiness, a 400 Bad Request will be returned.

```APIDOC
## POST /api/v1/business/program

### Description
Creates a new program for a superbusiness. Programs have their own funding accounts, allowing a business to separate funds. For further info, refer to Getting Started in the docs.
If you haven't been designated as a superbusiness, this endpoint will return a 400 Bad Request status.

### Method
POST

### Endpoint
/api/v1/business/program

### Parameters
#### Request Body
- **name** (string) - Required - The program's name.
- **logoUrl** (string) - Optional - Logo URL can be a link to your program's logo image. This is optional and will only be displayed on your GiveCard admin dashboard.
- **productType** (string) - Optional - Enum: ["cards", "bank_transfers", "on_demand_cards"] - The type of product for the program.

### Request Example
```json
{
  "name": "Summer Promotions",
  "logoUrl": "https://example.com/logo.png",
  "productType": "cards"
}
```

### Response
#### Success Response (200)
- **program** (object) - An object containing the details of the newly created program.
  - **id** (string) - The unique identifier for the program.
  - **name** (string) - The name of the program.
  - **productType** (string) - The type of product for the program.
  - **createdAt** (string) - The date and time the program was created.

#### Response Example
```json
{
  "program": {
    "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "name": "Summer Promotions",
    "productType": "cards",
    "createdAt": "2023-10-27T10:00:00Z"
  }
}
```

#### Error Response (400, 404, 409, 500)
- **fieldViolations** (array) - Describes all violations in a client request.
  - **field** (string) - The field that caused the violation.
  - **description** (string) - A description of the violation.
```

--------------------------------

### cURL POST Request Example for Tagging Cards

Source: https://givecard.readme.io/reference/managecard

This snippet demonstrates how to make a POST request to the /api/v1/cards/tag endpoint using cURL. It includes necessary headers for content type and general acceptance. This is useful for programmatically tagging cards within the Givecard system.

```shell
curl --request POST \
     --url https://api.dev.givecard.dev/api/v1/cards/tag \
     --header 'accept: */*' \
     --header 'content-type: application/json'
```

--------------------------------

### Create Velocity Rule for Commercial Expense Program (JSON)

Source: https://givecard.readme.io/reference/velocity-spend-rules

This example demonstrates how to create a velocity rule for a commercial expense program. It defines daily, weekly, monthly, and single transaction velocity limits. The 'programId' should be replaced with the actual program ID.

```json
{
	"name": "Commercial Expense Velocity Limits",
	"description": "This rule sets the spend limits for our commercial expense program",
	"type": "velocity",
	"applyTo": "program",
  "programId": "33c315e1-b20f-4d3c-beb6-07ac661121f9", // substitute with real programId
	"restrictions": [
		{
		  "type": "velocity",
		  "velocityValue": "2500",
  		"velocityCycle": "monthly"
		},
		{
		  "type": "velocity",
		  "velocityValue": "1000",
  		"velocityCycle": "weekly"
		},
		{
		  "type": "velocity",
		  "velocityValue": "500",
  		"velocityCycle": "daily"
		},
		{
		  "type": "velocity",
		  "velocityValue": "50",
  		"velocityCycle": "single_transaction"
		}
	]
}
```

--------------------------------

### Python Example for Givecard API Authentication Test

Source: https://givecard.readme.io/reference/auth

This Python code snippet shows how to test the Givecard API authentication using the 'requests' library. It sends a GET request to the base URL and handles potential errors. Ensure your authentication credentials are included in the request headers.

```python
import requests

api_url = "https://api.dev.givecard.dev/api/v1"

headers = {
    "accept": "*/*"
    # Add your authentication headers here, e.g.:
    # "Authorization": "Bearer YOUR_API_KEY"
}

try:
    response = requests.get(api_url, headers=headers)
    response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)

    print(f"Status Code: {response.status_code}")
    print(f"Response Body: {response.json()}")

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")
    print(f"Status Code: {response.status_code}")
    print(f"Response Body: {response.text}")
except requests.exceptions.RequestException as req_err:
    print(f"Other request error occurred: {req_err}")

```

--------------------------------

### POST /websites/givecard_readme_io

Source: https://givecard.readme.io/reference/issuevirtualcardandgeneratelinkv1

Creates a virtual card and returns a unique activation link for the cardholder to view the virtual card details. This takes in either an email or phoneNumber, not both. This does not send an email or SMS, refer to IssueVirtualCards to send the card directly to the cardholder.

```APIDOC
## POST /websites/givecard_readme_io

### Description
Creates a virtual card and returns a unique activation link for the cardholder to view the virtual card details. This takes in either an email or phoneNumber, not both. This does not send an email or SMS, refer to IssueVirtualCards to send the card directly to the cardholder.

### Method
POST

### Endpoint
/websites/givecard_readme_io

### Parameters
#### Request Body
- **email** (string) - Optional - The email address of the cardholder.
- **phoneNumber** (string) - Optional - The phone number of the cardholder.

### Request Example
```json
{
  "email": "cardholder@example.com"
}
```

### Response
#### Success Response (200)
- **activationLink** (string) - The unique activation link for the virtual card.

#### Response Example
```json
{
  "activationLink": "https://example.com/activate/very-unique-link-123"
}
```
```

--------------------------------

### PHP Example for Givecard API Authentication Test

Source: https://givecard.readme.io/reference/auth

This PHP code snippet illustrates how to test the Givecard API authentication using cURL. It sends a GET request to the API's base URL and displays the response status and body. Remember to include necessary authentication headers for the request to succeed.

```php
<?php

$url = 'https://api.dev.givecard.dev/api/v1';

$ch = curl_init($url);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'accept: */*'
    // Add your authentication headers here, e.g.:
    // 'Authorization: Bearer YOUR_API_KEY'
));

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if (curl_errno($ch)) {
    echo 'cURL error: ' . curl_error($ch);
} else {
    echo 'HTTP Status Code: ' . $httpCode . "\n";
    echo 'Response Body: ' . $response;
}

curl_close($ch);

?>

```

--------------------------------

### Create Differentiated Merchant Velocity Limits (JSON)

Source: https://givecard.readme.io/reference/velocity-spend-rules

This example demonstrates setting different monthly velocity limits for various merchant categories. It applies a general $500 limit, but specifically restricts ATMs to $150 and florists to $200 per month.

```json
{
	"name": "Monthly Merchant Velocity Limits",
	"description": "This sets our spend limits at different merchants",
	"type": "velocity",
	"applyTo": "business",
	"restrictions": [
		{
		  "type": "merchant_category",
  		"value": "AUTOMATED_CASH_DISBURSE",
      "velocityCycle": "monthly",
  		"velocityValue": "150"
		},
    {
		  "type": "merchant_category",
  		"value": "FLORISTS",
      "velocityCycle": "monthly",
  		"velocityValue": "200"
		},
    {
      "velocityCycle": "monthly",
  		"velocityValue": "500"
		}
	]
}
```

--------------------------------

### cURL Request to Simulate Card Shipment

Source: https://givecard.readme.io/reference/simulate

An example cURL command to send a POST request to the Givecard API to simulate a card shipment. This demonstrates how to set the request method, URL, and headers.

```shell
curl --request POST \
     --url https://api.dev.givecard.dev/api/v1/business/cardOrders/cardOrderId/simulateShipment \
     --header 'accept: */*'
```

--------------------------------

### Get Funding Account Balance

Source: https://givecard.readme.io/reference/fundingaccount

Retrieves the funding account balance for a business. Superbusinesses can specify a program ID to get a specific program's balance or an account type if multiple funding accounts exist.

```APIDOC
## GET /api/v1/business/fundingAccount/balance

### Description
Gets the business's funding account's balance. If called by a superbusiness, this will return the balance of the superbusiness Funding account, not one for a program, unless a programId is passed in.

### Method
GET

### Endpoint
`https://api.dev.givecard.dev/api/v1/business/fundingAccount/balance`

### Parameters
#### Query Parameters
- **programId** (string) - Optional - To get the funding account balance of a specific program, Superbusinesses may pass in a Program ID. Otherwise this endpoint will return the balance of the Superbusiness funding account.
- **accountType** (string) - Optional - Account Type is only necessary for superbusinesses that have multiple funding accounts. If there are multiple funding accounts for the superbusiness and no account type is given, it will default to returning to the type 'card' funding account type. Allowed values: `card`, `bank_transfer`, `on_demand_card`.

### Request Example
```json
{
  "programId": "prog_123",
  "accountType": "card"
}
```

### Response
#### Success Response (200)
- **balance** (string) - A decimal representing dollars, for example: 11.23

#### Response Example
```json
{
  "balance": "123.45"
}
```

#### Error Response (400)
- **badRequest** (object) - Describes violations in a client request. This error type focuses on the syntactic aspects of the request.
  - **fieldViolations** (array of objects) - Describes all violations in a client request.
    - **description** (string) - A description of why the request element is bad.
    - **field** (string) - A path leading to a field in the request body.
  - **errorInfo** (object)
    - **reason** (string) - The reason of the error. Allowed values: `UNKNOWN`, `OUTDATED_VERSION`.
    - **fieldErrors** (object)
      - **localizedMessage** (object)
        - **locale** (string) - The locale used following the specification defined at http://www.rfc-editor.org/rfc/bcp/bcp47.txt.
        - **message** (string) - The localized error message in the above locale.
    - **requestInfo** (object)
      - **requestId** (string) - An opaque string that should only be interpreted by the service generating it.
      - **servingData** (string) - Any data that was used to serve this request.
```

--------------------------------

### Simulate Card Order Shipped (Sandbox)

Source: https://givecard.readme.io/reference/simulatecardordershippedv1

Simulates a card order being shipped in the sandbox environment. This action updates the order status to 'shipped' and associates a tracking number with the card.

```APIDOC
## POST /websites/givecard_readme_io/simulate_shipped

### Description
Simulates a card order being shipped in the sandbox. When this endpoint is called, the order status is set to 'shipped' and a tracking number is assigned to the card.

### Method
POST

### Endpoint
/websites/givecard_readme_io/simulate_shipped

### Parameters
#### Query Parameters
- **orderId** (string) - Required - The ID of the order to simulate shipping for.

### Request Example
```json
{
  "orderId": "ORD12345"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the order has been simulated as shipped.
- **orderStatus** (string) - The updated status of the order ('shipped').
- **trackingNumber** (string) - The tracking number assigned to the shipment.

#### Response Example
```json
{
  "message": "Order ORD12345 simulated as shipped successfully.",
  "orderStatus": "shipped",
  "trackingNumber": "TRK98765"
}
```
```

--------------------------------

### Get Card Load History - OpenAPI Specification

Source: https://givecard.readme.io/reference/getcardloadhistoryv1

This snippet defines the GET endpoint for retrieving the load history of a specific card. It accepts a card ID and optional date range parameters. The response includes details about card loads or potential errors.

```json
{
  "openapi": "3.0.0",
  "info": {
    "description": "GiveCard API Specification",
    "title": "GiveCard APIs",
    "version": "1.0.0"
  },
  "paths": {
    "/api/v1/cards/{cardId}/loadHistory": {
      "get": {
        "security": [
          {
            "apiKey": [
              "[]"
            ]
          }
        ],
        "description": "Returns all loads for a given card. Accepts optional date range query parameters.",
        "tags": [
          "manageCard"
        ],
        "summary": "# Get Card Load History",
        "operationId": "getCardLoadHistoryV1",
        "parameters": [
          {
            "x-go-name": "CardId",
            "description": "Either a card's ID or external ID acceptable.",
            "name": "cardId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "x-go-name": "DateFrom",
            "description": "Optionally query for loads after a certain date in the RFC3339 format YYYY-MM-DDThh:mm:ssZ.",
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "x-go-name": "DateTo",
            "description": "Optionally query for loads before a certain date in the RFC3339 format YYYY-MM-DDThh:mm:ssZ.",
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/ApiGetCardLoadHistoryResponse"
          },
          "400": {
            "$ref": "#/components/responses/WhimsyErrorResponse"
          },
          "404": {
            "$ref": "#/components/responses/WhimsyErrorResponse"
          },
          "500": {
            "$ref": "#/components/responses/WhimsyErrorResponse"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.dev.givecard.dev"
    }
  ],
  "components": {
    "responses": {
      "ApiGetCardLoadHistoryResponse": {
        "description": "",
        "content": {
          "*/*": {
            "schema": {
              "$ref": "#/components/schemas/ApiGetCardDetailsResponseBody"
            }
          }
        }
      },
      "WhimsyErrorResponse": {
        "description": "",
        "content": {
          "*/*": {
            "schema": {
              "$ref": "#/components/schemas/WhimsyError"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "name": "authorization",
        "in": "header"
      }
    },
    "schemas": {
      "Address": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "x-go-name": "City"
          },
          "country": {
            "type": "string",
            "x-go-name": "Country"
          },
          "postalCode": {
            "type": "string",
            "x-go-name": "PostalCode"
          },
          "state": {
            "type": "string",
            "x-go-name": "State"
          },
          "street": {
            "type": "string",
            "x-go-name": "Street"
          },
          "street2": {
            "type": "string",
            "x-go-name": "Street2"
          }
        },
        "x-go-package": "whimsy/pkg/models"
      },
      "ApiCard": {
        "type": "object",
        "properties": {
          "bin": {
            "description": "The card's Bank Identification Number.",
            "type": "string",
            "x-go-name": "Bin"
          },
          "businessID": {
            "$ref": "#/components/schemas/UUID"
          },
          "createdAt": {
            "description": "The time that the card was ordered in UTC.",
            "type": "string",
            "format": "date-time",
            "x-go-name": "CreatedAt"
          },
          "expirationDate": {
            "description": "The card's expiration date in the format MMYY.",
            "type": "string",
            "x-go-name": "ExpirationDate"
          },
          "externalId": {
            "description": "The external ID is a card's unique identifier that begins with the first 4 characters of the business name and is printed on the back of physical cards.",
            "type": "string",
            "x-go-name": "ExternalId"
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "x-go-name": "ID"
          },
          "last4": {
            "description": "The last 4 digits of the 16-digit card number used to make purchases.",
            "type": "string",
            "x-go-name": "Last4"
          },
          "lastLoadedAt": {
            "description": "The time that the card was last loaded in UTC."
          }
        }
      }
    }
  }
}
```

--------------------------------

### Create Monthly ATM/Florist Spend Limit Rule (JSON)

Source: https://givecard.readme.io/reference/velocity-spend-rules

This example shows how to set a monthly spend limit of $500 specifically for ATMs and florists. It applies to a business and uses merchant category restrictions. To limit spending elsewhere, a separate merchant_allow rule would be needed.

```json
{
	"name": "Monthly ATM limit",
	"description": "This card can't spend more than $500/m at an ATM OR florists",
	"type": "velocity",
	"applyTo": "business",
  "velocityCycle": "monthly",
  "velocityValue": "500",
	"restrictions": [
		{
		  "type": "merchant_category",
  		"value": "AUTOMATED_CASH_DISBURSE"
		},
    {
		  "type": "merchant_category",
  		"value": "FLORISTS"
		}
	]
}
```
Tokens:
Raw