BVbvnk
Fiat Payments

Create on-ramp payment rule

Changed on

Creates a rule that links a crypto wallet to a fiat virtual account to automatically handle on-ramp (fiat → crypto) flow. The trigger field defines the flow to activate:

  • payment:payin:fiat — on-ramp

For more information, see the Automate Fiat-to-Crypto Transfers guide.

post/payment/v1/rules

Request

Request body

referencestring required

Unique identifier of the transaction.

triggerstring required

Originating event that triggers the automated action. Use payment:payin:fiat for on-ramp fiat → crypto.

walletIdstring required

BVNK wallet ID for the wallet from/to which funds will be sent.

Example request

{
  "reference": "REF558628",
  "trigger": "payment:payin:fiat",
  "walletId": "a:24122329329347:HsdJVhW:1",
  "fees": {
    "customerFee": {
      "amount": 100.5,
      "currency": "USD"
    }
  },
  "beneficiary": {
    "currency": "USDT",
    "entity": {
      "customerIdentifier": "HJHJ4668KB",
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1990-05-15",
      "address": {
        "addressLine1": "123 Main Street",
        "addressLine2": "Apartment 456",
        "postalCode": "NW1 4NP",
        "city": "London",
        "country": "GB",
        "stateCode": "AL"
      },
      "relationshipType": "SELF_OWNED"
    },
    "cryptoAddress": {
      "address": "0x12323542636474747",
      "tag": "332455"
    }
  }
}

Response

Success

idstring uuid

Unique identifier for the payment rule. You can use this value to update the rule via `/payment/v1/rules/{id}.

referencestring
triggerstring
statusstring

Rule status. ACTIVE while the rule applies to incoming pay-ins on the wallet.

metadataMetadata

Custom metadata key-value pairs. Structure: key: value. Restrictions:

  • Maximum five keys.

  • Each key maximum length 50 characters.

  • Each value maximum length 100 characters.

  • Keys and values must be simple strings.

updatedAtstring date-time
createdAtstring date-time

Example response

{
  "id": "98c0bb03-567f-11f0-b26e-6b1848874a27",
  "reference": "REF558628",
  "trigger": "payment:payin:fiat",
  "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": "123 Main St",
        "addressLine2": "Some address Line 2",
        "city": "New York",
        "region": "NY",
        "postCode": "10001",
        "country": "US"
      }
    },
    "cryptoAddresses": {
      "network": "ETHEREUM",
      "addresses": [
        "0x12323542636474747"
      ],
      "tag": "332455"
    }
  },
  "metadata": {
    "source": "api",
    "orderId": "ORD-48213"
  },
  "updatedAt": "2025-07-01T13:31:02.52Z",
  "createdAt": "2025-07-01T13:30:02.52Z"
}

Changes

  • c386d436bf2cRevision changes
    • breaking

      the request property / became required

    • breaking

      the request property / became required

    • breaking

      the request property /////// became required

    • breaking

      the request property ////// became required

    • breaking

      the request property /////// became required

    • breaking

      the request property ////// became required

    • warning

      removed the request property ///////

    • warning

      removed the request property ///////

    • info

      added the new ARBITRUM enum value to the request property //

    • info

      added the new ARC enum value to the request property //

    • info

      added the new BASE enum value to the request property //

  • 97d6c0d2fe2eRevision changes
    • breaking

      the / response's property type changed from object to array for status

    • breaking

      the / response's property type changed from object to array for status

    • breaking

      the / response's property type changed from object to array for status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status