Skip to main content

Automate fiat-to-crypto transfers

Create payment rule​

To create a rule that links a fiat virtual account to a crypto blockchain address, send the POST /payment/v1/rules request with the following payload.

For the detailed description of the payload, refer to the Create Payment Rule API reference. 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.
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.

{
    "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",
                "region": "Île-de-France",
                "postCode": "75008",
                "country": "FR"
            }
        },
        "cryptoAddress": {
            "network": "ETHEREUM",
            "address": "0x12323542636474747",
            "tag": "332455"
        }
    }
}

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.

{
    "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 reference for details.

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

Click to expand the list of properties you can update
  • beneficiary.cryptoAddress.address
  • beneficiary.cryptoAddress.network
  • beneficiary.cryptoAddress.tag
  • beneficiary.entity.address.addressLine1
  • beneficiary.entity.address.addressLine2
  • beneficiary.entity.address.city
  • beneficiary.entity.address.country
  • beneficiary.entity.address.postCode
  • beneficiary.entity.address.region
  • beneficiary.entity.customerIdentifier
  • beneficiary.entity.dateOfBirth (Individual)
  • beneficiary.entity.firstName (Individual)
  • beneficiary.entity.lastName (Individual)
  • beneficiary.entity.legalName (Company)
  • beneficiary.entity.registrationNumber (Company)
  • beneficiary.entity.relationshipType
  • beneficiary.entity.type
  • fees.customerFee.amount
  • fees.customerFee.currency
  • paidCurrency

See the example payloads for different use cases:

{
    "fees": {
        "customerFee": {
            "amount": 3.5,
            "currency": "USD"
        }
    }
}

Payment webhooks​

To receive notifications about operations, use the following webhooks:

For more information about webhooks, refer to Configure webhooks.

Last updated on