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 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.

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.

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.

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.

C#

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",
        }
      ),
  }
);

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.

{
  "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.

C#

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",
        }
      ),
  }
);

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 API with a default request that includes rates and the organization ID.

C#

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

You can customize the request with additional request parameters 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.

C#

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