# Automate fiat-to-crypto transfers

> To create a rule that links a fiat virtual account to a crypto blockchain address, send the [`POST /payment/v1/rules`](../../../api-explorer/endpoints/payment-rule-create) request with the following payload.

## Create payment rule

To create a rule that links a fiat virtual account to a crypto blockchain address, send the [`POST /payment/v1/rules`](../../../api-explorer/endpoints/payment-rule-create) request with the following payload.

Note the following important parameters:

* `trigger` specifies the originating event which triggers this automated action. For fiat-to-crypto on-ramping, use `payment:payin:fiat`.
* `customerIdentifier` is the unique identifier of the customer.

:::info Wallet validation
When you create a payment rule to automatically on-ramp funds to a blockchain address, BVNK validates the address format. This ensures that funds converted to crypto settle successfully.
:::

```json Example request for Individual
{
    "reference": "REF558628",
    "trigger": "event:payment:payin",
    "walletId": "a:24145329329347:HsdJVhW:1",
    "fees": {
        "customerFee": {
            "amount": 0.5,
            "currency": "USD"
        }
    },
    "beneficiary": {
        "currency": "USDT",
        "entity": {
            "type": "COMPANY",
            "customerIdentifier": "9401203948572394595",
            "legalName": "3Com",
            "relationshipType": "SELF_OWNED",
            "registrationNumber": "ABC21D21FZC",
            "address": {
                "addressLine1": "Champs-Élysées 101",
                "addressLine2": "Apartment 3B",
                "city": "Paris",
                "postalCode": "75008",
                "country": "FR"
            }
        },
        "cryptoAddress": {
            "network": "ETHEREUM",
            "address": "0x12323542636474747",
            "tag": "332455"
        }
    }
}
```

```json Example request for Company
{
    "reference": "REF7658628",
    "trigger": "event:payment:payin",
    "walletId": "a:25031045518203:IUMTTAY:1",
    "fees": {
        "customerFee": {
            "amount": 1,
            "currency": "USD"
        }
    },
    "paidCurrency": "ETH",
    "beneficiary": {
        "entity": {
            "type": "INDIVIDUAL",
            "customerIdentifier": "9401203948572394595",
            "firstName": "John",
            "lastName": "Doe",
            "dateOfBirth": "1990-05-15",
            "relationshipType": "SELF_OWNED",
            "address": {
                "addressLine1": "1600 Amphitheatre Parkway",
                "addressLine2": "Building 43",
                "city": "Mountain View",
                "stateCode": "CA",
                "postalCode": "94043",
                "country": "US"
            }
        },
        "cryptoAddress": {
            "network": "Ethereum",
            "address": "0xDDCD0Aa2C21d2d02ec0977565D037aBC67F7F151"
        }
    }
}
```

Upon successful linking of the fiat virtual account to the blockchain address, the API returns an HTTP `200 OK` status code along with a JSON object confirming the operation.

```json Example Response
{
    "id": "98c0bb03-567f-11f0-b26e-6b1848874a27",
    "reference": "REF558628",
    "trigger": "event:payment:payin",
    "status": "ACTIVE",
    "fees": {
        "customerFee": {
            "amount": 0.5,
            "currency": "USD"
        }
    },
    "originator": {
        "currency": "USD",
        "walletId": "acc:22041242429000:3MPpU:0"
    },
    "beneficiary": {
        "currency": "USDT",
        "entity": {
            "legalName": "3Com",
            "type": "COMPANY",
            "relationshipType": "SELF_OWNED",
            "registrationNumber": "ABC21D21FZC",
            "address": {
                "addressLine1": "Champs-Élysées 101",
                "addressLine2": "Apartment 3B",
                "city": "Paris",
                "region": "Île-de-France",
                "postCode": "75008",
                "country": "FR"
            }
        },
        "cryptoAddresses": {
            "network": "ETHEREUM",
            "addresses": [
                "0x12323542636474747"
            ],
            "tag": "332455"
        }
    },
    "metadata": {},
    "updatedAt": "2025-07-01T13:31:02.52.000000000Z",
    "createdAt": "2025-07-01T13:30:02.52.000000000Z"
}
```

Whenever funds land into your wallet (identified by the `walletId` in the response), the system automatically converts them to the specified crypto and sends them to the specified blockchain address (detailed in `cryptoAddresses.addresses`).

If the operation was not successful, the API returns an HTTP `400 BAD REQUEST` status code along with a JSON error code. See the [Errors](../../../api-explorer/api-overview/errors) reference for details.

```json Example of Failed Request
{
    "code": "bvnk:payment:rules:4002",
    "status": "BAD_REQUEST",
    "message": "Address validation error"
}
```

## Update payment rule

To change a previously created payment rule, send the [`PATCH payment/v1/rules/{id}`](../../../api-explorer/endpoints/payment-rule-update) request with the `id` received in the successful response earlier, here, `98c0bb03-567f-11f0-b26e-6b1848874a27`.

In the request body, specify only properties that you want to update. The omitted fields will remain unchanged, and sending a null for a nullable property will clear it.

See the example payloads for different use cases:

  
    ```json Update Fees
    {
        "fees": {
            "customerFee": {
                "amount": 3.5,
                "currency": "USD"
            }
        }
    }
    ```
    
    
    ```json
    {
        "beneficiary": {
            "entity": {
                "type": "COMPANY",
                "legalName": "APEX Ltd."
            }
        }
    }
    ```
    
    
    ```json
    {
        "beneficiary": {
            "cryptoAddress": {
                "address": "0x742d35cc6634C0532925a3b844Bc9e7595f0bEA5",
                "network": "Ethereum"
            }
        }
    }
    ```
    
  

## Deactivate payment rule

To activate or deactivate a payment rule, send the [`POST /payment/v1/rules/{id}/action`](../../../api-explorer/endpoints/payment-rule-action) request with the `id` received in the successful response earlier, here, `98c0bb03-567f-11f0-b26e-6b1848874a27`.

  
    To activate a payment rule, send the [`POST /payment/v1/rules/{id}/action`](../../../api-explorer/endpoints/payment-rule-action) request with the `id` received in the successful response earlier, here, `98c0bb03-567f-11f0-b26e-6b1848874a27`.

    ```json Example request to activate a payment rule
    {
        "action": "ACTIVATE"
    }
    ```
  
  
    To deactivate a payment rule, send the [`POST /payment/v1/rules/{id}/action`](../../../api-explorer/endpoints/payment-rule-action) request with the `id` received in the successful response earlier, here, `98c0bb03-567f-11f0-b26e-6b1848874a27`.

    ```json Example request to deactivate a payment rule
    {
        "action": "DEACTIVATE"
    }
    ```
  

Only one rule can be active for the same wallet. You can deactivate a rule and create another one for that wallet. However, if you activate the first wallet again, it won't be applied.

## Payment webhooks

To receive notifications about operations, use the following webhooks:

* [Incoming fiat payment status change](../../../api-explorer/bvnk-webhooks/payment-payin-status-change)
* [Cryptocurrency payment status change](../../../api-explorer/bvnk-webhooks/crypto-status-change)

For more information about webhooks, refer to [Configure webhooks](../../get-started/create-webhook-listener.mdx).