---
title: "Create on-ramp payment rule"
method: POST
path: "/payment/v1/rules"
tags: ["Fiat Payments"]
---

# Create on-ramp payment rule

`POST /payment/v1/rules`

## Request

- Base URL: `https://api.sandbox.bvnk.com`
- URL: `https://api.sandbox.bvnk.com/payment/v1/rules`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/docs/payment/v1/rules/post.ts> (a function with typed inputs; its response is checked against the schema)

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](/bvnk/use-cases/on-off-ramp/automate-fiat-to-crypto-transfers/) guide.

## Request body

- object: Details required to link the crypto wallet and define the automated action.
  - `reference` string, required: Unique identifier of the transaction.
  - `trigger` string, required: Originating event that triggers the automated action. Use `payment:payin:fiat` for on-ramp fiat → crypto.
  - `walletId` string, required: BVNK wallet ID for the wallet from/to which funds will be sent.
  - `fees` object: Use to charge a fee from your end customer.
    - `customerFee` MoneyFeeV2
      - `amount` number, required: Fee amount in fiat or crypto currency units.
      - `currency` string, required: Currency code. Supports both fiat (ISO-4217) and cryptocurrencies.
  - `beneficiary` object, required: Details about the recipient of the crypto funds.
    - `currency` string: The cryptocurrency being sent (e.g., USDT, BTC, ETH).
    - `entity` union, required
      - PaymentRuleIndividual
        - `type` 'INDIVIDUAL', required: Entity type
        - `customerIdentifier` string, required: Unique customer reference.
        - `firstName` string, required: First name
        - `lastName` string, required: Last name
        - `dateOfBirth` string, date: Date of birth in YYYY-MM-DD format
        - `address` PaymentRuleAddress
          - `addressLine1` string, required: Main address
          - `addressLine2` string: Apartment numbers or suite number
          - `postalCode` string, required: Postal code
          - `city` string, required: City
          - `country` string, required: 2-letter country code in the ISO 3166-1 alpha-2 format.
          - `stateCode` string: 2-letter state code. **Required for US customers**.
        - `relationshipType` 'SELF_OWNED' | 'THIRD_PARTY', required: Relationship type
      - PaymentRuleCompany
        - `type` 'COMPANY', required: Entity type
        - `customerIdentifier` string, required: Unique customer reference.
        - `legalName` string, required: Legal company name
        - `registrationNumber` string: Company registration number.
        - `address` PaymentRuleAddress
          - `addressLine1` string, required: Main address
          - `addressLine2` string: Apartment numbers or suite number
          - `postalCode` string, required: Postal code
          - `city` string, required: City
          - `country` string, required: 2-letter country code in the ISO 3166-1 alpha-2 format.
          - `stateCode` string: 2-letter state code. **Required for US customers**.
        - `relationshipType` 'SELF_OWNED' | 'THIRD_PARTY', required: Relationship type
    - `cryptoAddress` PaymentRuleCryptoAddress, required: Crypto destination details.
      - `network` 'TRON' | 'ETHEREUM' | 'LITECOIN' | 'BITCOIN' | 'RIPPLE' | 'DOGECOIN' | 'SOLANA' | 'ALGORAND' | 'CARDANO' | 'BINANCE' | 'POLYGON' | 'BITCOIN_CASH' | 'ARC' | 'ARBITRUM' | 'BASE', required: Blockchain network.
      - `address` string, required: Crypto wallet address.
      - `tag` string: Optional tag/memo for certain cryptocurrencies (e.g., XRP, XLM).

## Response `200`

Success

- object
  - `id` string, uuid: Unique identifier for the payment rule. You can use this value to update the rule via [`/payment/v1/rules/{id}](https://docs.bvnk.com/bvnk/api-explorer/endpoints/payment-rule-update).
  - `reference` string
  - `trigger` string
  - `status` string: Rule status. `ACTIVE` while the rule applies to incoming pay-ins on the wallet.
  - `fees` object
    - `customerFee` object
      - `amount` number
      - `currency` string
  - `originator` object
    - `currency` string
    - `walletId` string
  - `beneficiary` object
    - `currency` string
    - `entity` object
      - `legalName` string
      - `type` string
      - `relationshipType` string
      - `registrationNumber` string
      - `address` object
        - `addressLine1` string
        - `addressLine2` string
        - `city` string
        - `region` string: State or region. Sent as `stateCode` in the create request.
        - `postCode` string: Postal code. Sent as `postalCode` in the create request.
        - `country` string
    - `cryptoAddresses` object: Destination crypto address, sent as `cryptoAddress` in the create request. The address is returned in the `addresses` array.
      - `network` string
      - `addresses` string[]
      - `tag` string
  - `metadata` Metadata: 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.
  - `updatedAt` string, date-time
  - `createdAt` string, date-time

## Other responses

- `400`: Bad request.
- `401`: Unauthorized.
- `403`: Forbidden.

## Changes

- **2026-11-06** `c386d436bf2c`: 6 breaking, 2 warning, 3 info
  - the request property `beneficiary/cryptoAddress` became required
  - the request property `beneficiary/entity` became required
  - the request property `beneficiary/entity/oneOf[#/components/schemas/PaymentRuleCompany]/address/country` became required
  - the request property `beneficiary/entity/oneOf[#/components/schemas/PaymentRuleCompany]/customerIdentifier` became required
  - …7 more
- **2026-06-16** `97d6c0d2fe2e`: 3 breaking, 3 warning, 3 info
  - the `details/errors` response's property type changed from `object` to `array` for status `400`
  - the `details/errors` response's property type changed from `object` to `array` for status `401`
  - the `details/errors` response's property type changed from `object` to `array` for status `403`
  - removed the optional property `details/errors/requestBody` from the response with the `400` status
  - …5 more

[Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/payment/v1/rules/post.md)

---

[API](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints.md) - [All operations](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/revisions/c386d436bf2c?raw)