> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Giving Block

> Connect to The Giving Block to accept cryptocurrency payments.

The Giving Block enables cryptocurrency fundraising for nonprofits, charities, universities, and faith-based organizations. It uses a redirect flow where the buyer completes the crypto payment on The Giving Block hosted page.

## Setup

The Giving Block does not provide self-service sign-up. [Contact their sales team](https://thegivingblock.com) to set up an account.

## Credentials

When setting up The Giving Block in the dashboard, configure the following credentials:

* **Login** - The API login username. This is different from the dashboard login.
* **Password** - The API password. This is different from the dashboard password.
* **Encryption key** - Used to decrypt webhooks sent from The Giving Block.
* **Encryption IV** - Used alongside the encryption key to decrypt webhooks.
* **USD Organisation ID** (optional) - The organization ID for processing USD transactions. Found in The Giving Block dashboard under **Organizations**.
* **GBP Organisation ID** (optional) - The organization ID for processing GBP transactions. Found in The Giving Block dashboard under **Organizations**.

At least one organization ID is required for each currency you want to process transactions for.

<Warning>
  Make sure to configure the correct organization ID for each currency. If incorrectly configured, a transaction may be adjusted to the captured amount in the wrong currency.
</Warning>

### Webhooks

The Giving Block connector requires webhooks to receive transaction status updates. After setting up the connector:

1. Copy the webhook URL from the Gr4vy dashboard.
2. Share the URL with The Giving Block support team to configure it for your account.

## Features

The Giving Block supports the following features:

* **Direct capture** - Payments are captured immediately at the time of authorization
* **Transaction sync** - Automatic synchronization of transaction status updates

## Supported countries

The Giving Block supports transactions from buyers in `GB` and `US`.

## Supported currencies

The Giving Block supports processing payments in `GBP` and `USD`.

## Limitations

The following features are not supported by this connector:

* **Delayed capture** - Authorizing a payment and capturing it later is not supported
* **Void** - Canceling an authorized transaction before capture is not supported
* **Refunds** - Full refunds are not supported
* **Partial refunds** - Partial refunds are not supported
* **Partial capture** - Capturing a portion of the authorized amount is not supported
* **Over capture** - Capturing more than the authorized amount is not supported
* **Partial authorization** - Accepting a partial amount is not supported
* **Payment method tokenization** - Storing payment methods for future use is not supported
* **Zero auth** - Zero-dollar verification transactions are not supported
* **Settlement reporting** - Automatic settlement reporting is not supported

Additional limitations:

* **Amount adjustment** - The captured amount of a transaction is automatically adjusted to the actual settled fiat amount received in the webhook from The Giving Block.
* `payment_service_transaction_id` changes between when the transaction is created and when it is captured.

## Integration

The default integration for The Giving Block uses a redirect to a hosted payments page.

Start by creating a new transaction with the following required fields.

<CodeGroup>
  ```csharp C# theme={"system"}
  var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
      Amount = 1299,
      Currency = "USD",
      Country = "US",
      PaymentMethod =
        TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
          new RedirectPaymentMethodCreate()
          {
            Method = "givingblock",
            RedirectUrl = "https://example.com/callback",
          }
        ),
    }
  );
  ```

  ```go Go theme={"system"}
  amount := int64(1299)
  currency := "USD"
  country := "US"
  method := "givingblock"
  redirectUrl := "https://example.com/callback"

  redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
    Method: method,
    RedirectUrl: redirectUrl,
  }
  paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)

  transactionCreate := components.TransactionCreate{
    Amount:        amount,
    Currency:      currency,
    Country:       &country,
    PaymentMethod: &paymentMethod,
  }

  transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)
  ```

  ```java Java theme={"system"}
  CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
    .transactionCreate(TransactionCreate.builder()
      .amount(1299L)
      .currency("USD")
      .country("US")
      .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
        .method("givingblock")
        .redirectUrl("https://example.com/callback")
        .build()))
      .build())
    .call();

  Transaction transaction = transactionResponse.transaction().orElse(null);
  ```

  ```php PHP theme={"system"}
  $transactionCreate = new TransactionCreate(
    amount: 1299,
    currency: 'USD',
    country: 'US',
    paymentMethod: new RedirectPaymentMethodCreate(
      method: 'givingblock',
      redirectUrl: 'https://example.com/callback'
    )
  );
  $response = $client->transactions->create($transactionCreate);
  $transaction = $response->transaction;
  ```

  ```python Python theme={"system"}
  transaction: models.Transaction = client.transactions.create(
    amount=1299,
    currency="USD",
    country="US",
    payment_method={
      "method": "givingblock",
      "redirect_url": "https://example.com/callback",
    }
  )
  ```

  ```ts TypeScript theme={"system"}
  const transaction = await client.transactions.create({
    amount: 1299,
    currency: "USD",
    country: "US",
    paymentMethod: {
      method: "givingblock",
      redirectUrl: "https://example.com/callback"
    }
  })
  ```
</CodeGroup>

After the transaction is created, the API response includes a `payment_method.approval_url` and the status is set to `buyer_approval_pending`. The approval URL expires after 7 days.

```json theme={"system"}
{
  "type": "transaction",
  "id": "ea1efdd0-20f9-44d9-9b0b-0a3d71e9b625",
  "payment_method": {
    "type": "payment-method",
    "approval_url": "https://cdn.gr4vy.com/connectors/..."
  },
  "method": "givingblock"
}
```

Redirect the buyer to the `approval_url` (open in a browser or Webview), where they can complete the crypto payment. Once the buyer completes the payment, the transaction progresses to a `capture_succeeded` state.

### Connection options

The Giving Block connector supports passing a default cryptocurrency when creating a transaction.

<CodeGroup>
  ```csharp C# highlight={6-12} theme={"system"}
  var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
      Amount = 1299,
      Currency = "USD",
      ConnectionOptions = new TransactionCreateConnectionOptions()
      {
        GivingblockGivingblock = new ConnectionOptionsGivingblockGivingblock()
        {
          DefaultCryptocurrency = "ETH",
        },
      },
      PaymentMethod =
        TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
          new RedirectPaymentMethodCreate()
          {
            Method = "givingblock",
            RedirectUrl = "https://example.com/callback",
          }
        ),
    }
  );
  ```

  ```go Go highlight={4-8} theme={"system"}
  connectionOptions := components.TransactionCreateConnectionOptions{
    GivingblockGivingblock: &components.ConnectionOptionsGivingblockGivingblock{
      DefaultCryptocurrency: gr4vy.String("ETH"),
    },
  }

  transactionCreate := components.TransactionCreate{
    Amount:            amount,
    Currency:          currency,
    Country:           &country,
    ConnectionOptions: &connectionOptions,
    PaymentMethod:     &paymentMethod,
  }

  transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)
  ```

  ```java Java highlight={5-7} theme={"system"}
  CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
    .transactionCreate(TransactionCreate.builder()
      .amount(1299L)
      .currency("USD")
      .connectionOptions(TransactionCreateConnectionOptions.builder()
        .givingblockGivingblock(ConnectionOptionsGivingblockGivingblock.builder()
          .defaultCryptocurrency("ETH")
          .build())
        .build())
      .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
        .method("givingblock")
        .redirectUrl("https://example.com/callback")
        .build()))
      .build())
    .call();
  ```

  ```php PHP highlight={5-7} theme={"system"}
  $transactionCreate = new TransactionCreate(
    amount: 1299,
    currency: 'USD',
    country: 'US',
    connectionOptions: new TransactionCreateConnectionOptions(
      givingblockGivingblock: new ConnectionOptionsGivingblockGivingblock(
        defaultCryptocurrency: 'ETH'
      )
    ),
    paymentMethod: new RedirectPaymentMethodCreate(
      method: 'givingblock',
      redirectUrl: 'https://example.com/callback'
    )
  );
  $response = $client->transactions->create($transactionCreate);
  ```

  ```python Python highlight={5-9} theme={"system"}
  transaction: models.Transaction = client.transactions.create(
    amount=1299,
    currency="USD",
    country="US",
    connection_options={
      "givingblock-givingblock": {
        "defaultCryptocurrency": "ETH",
      },
    },
    payment_method={
      "method": "givingblock",
      "redirect_url": "https://example.com/callback",
    }
  )
  ```

  ```ts TypeScript highlight={5-9} theme={"system"}
  const transaction = await client.transactions.create({
    amount: 1299,
    currency: "USD",
    country: "US",
    connectionOptions: {
      "givingblock-givingblock": {
        defaultCryptocurrency: "ETH",
      },
    },
    paymentMethod: {
      method: "givingblock",
      redirectUrl: "https://example.com/callback"
    }
  })
  ```
</CodeGroup>

This automatically sets the default crypto currency used when the user is redirected to The Giving Block, allowing
for a more smooth experience between your UI, where a user may have already selected a currency earlier.

### Currency conversion rates

The Giving Block connector supports fetching the latest crypto rates used to calculate fiat amounts to crypto amounts. This calls the [list currencies](https://docs.thegivingblock.com/api-reference#list-currencies) API with a default request that includes rates and the organization ID.

<CodeGroup>
  ```csharp C# theme={"system"}
  var res = await client.PaymentServiceDefinitions.SessionAsync(
    paymentServiceDefinitionId: "givingblock-givingblock",
    requestBody: new Dictionary<string, object>()
    {
      { "includeRates", true },
    }
  );
  ```

  ```go Go theme={"system"}
  res, err := client.PaymentServiceDefinitions.Session(
    ctx,
    "givingblock-givingblock",
    map[string]any{
      "includeRates": true,
    },
  )
  ```

  ```java Java theme={"system"}
  var res = client.paymentServiceDefinitions().session()
    .paymentServiceDefinitionId("givingblock-givingblock")
    .requestBody(Map.ofEntries(
      Map.entry("includeRates", true)
    ))
    .call();
  ```

  ```php PHP theme={"system"}
  $response = $client->paymentServiceDefinitions->session(
    paymentServiceDefinitionId: 'givingblock-givingblock',
    requestBody: [
      'includeRates' => true,
    ]
  );
  ```

  ```python Python theme={"system"}
  res = client.payment_service_definitions.session(
    payment_service_definition_id="givingblock-givingblock",
    request_body={
      "includeRates": True,
    },
  )
  ```

  ```ts TypeScript theme={"system"}
  const res = await client.paymentServiceDefinitions.session({
    includeRates: true,
  }, "givingblock-givingblock")
  ```
</CodeGroup>

You can customize the request with additional [request parameters](https://docs.thegivingblock.com/api-reference#list-currencies) supported by this API.

If you have more than one The Giving Block connector configured, target a specific connector by using `client.paymentServices.session` with the `payment_service_id` instead.

<CodeGroup>
  ```csharp C# theme={"system"}
  var res = await client.PaymentServices.SessionAsync(
    paymentServiceId: "fffd152a-9532-4087-9a4f-de58754210f0",
    requestBody: new Dictionary<string, object>()
    {
      { "includeRates", true },
    }
  );
  ```

  ```go Go theme={"system"}
  res, err := client.PaymentServices.Session(
    ctx,
    "fffd152a-9532-4087-9a4f-de58754210f0",
    map[string]any{
      "includeRates": true,
    },
  )
  ```

  ```java Java theme={"system"}
  var res = client.paymentServices().session()
    .paymentServiceId("fffd152a-9532-4087-9a4f-de58754210f0")
    .requestBody(Map.ofEntries(
      Map.entry("includeRates", true)
    ))
    .call();
  ```

  ```php PHP theme={"system"}
  $response = $client->paymentServices->session(
    paymentServiceId: 'fffd152a-9532-4087-9a4f-de58754210f0',
    requestBody: [
      'includeRates' => true,
    ]
  );
  ```

  ```python Python theme={"system"}
  res = client.payment_services.session(
    payment_service_id="fffd152a-9532-4087-9a4f-de58754210f0",
    request_body={
      "includeRates": True,
    },
  )
  ```

  ```ts TypeScript theme={"system"}
  const res = await client.paymentServices.session({
    includeRates: true,
  }, "fffd152a-9532-4087-9a4f-de58754210f0")
  ```
</CodeGroup>