--- title: "Create payment" method: POST path: "/api/v1/pay/summary" tags: ["Crypto Payments"] --- # Create payment `POST /api/v1/pay/summary` ## Request - Base URL: `https://api.sandbox.bvnk.com` - URL: `https://api.sandbox.bvnk.com/api/v1/pay/summary` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates an incoming (type IN) or outcoming (type OUT) crypto payment. Alternatively, it creates a crypto payment that is either sent via a Customer's wallet or deposited into it. For more information, see the [Make Crypto Payments](https://docs.bvnk.com/bvnk/use-cases/stablecoin-payments-for-platforms/send-stablecoin-via-customers-wallet) guide. There are two flows depending on specifying `payOutDetails`: - If you add `PayOutDetails` with all its child parameters, the payment is successfully created and the funds are sent to the specified wallet, with no further actions needed. - If not included in the request, in the response you receive `redirectUrl`. This is a link to a page, where to you can redirect your Customer so they can finalize the payment. Also you can route a payout through your customer's wallet by setting `flow` to `EMBEDDED_CRYPTO` and providing `embeddedCustomerDetails`. Funds are debited from your pre-funded partner wallet, converted to crypto at BVNK, then paid out via the customer's wallet. For more information, see [Send stablecoin payments via customer's wallet](https://docs.bvnk.com/bvnk/use-cases/stablecoin-payments-for-platforms/send-stablecoin-via-customers-wallet). To preview a payment without creating it, use the [`POST /api/v1/pay/summary/dry-run`](/bvnk/api-explorer/endpoints/payment-dry-run/) endpoint instead. It returns the full payment summary, including the exchange rate, fees, and converted amounts, without creating a payment or moving any funds. ## Request body - union: The request data required to create a payment in or a payment out. - PayRequestInDto: Request data for an incoming crypto payment (`type: IN`). - `walletId` string, required: Identifier for the debit wallet associated with the transaction. - `merchantId` string: **Deprecated. Don't use, if you specify `walletId`**. Your Merchant ID. You can find it on the Merchant Details page in your account. - `amount` number, required: Payment amount. The minimum cryptocurrency deposit amount to be processed is 5 EUR. - `expiryMinutes` integer: The time period in minutes after which payment expires. Defaults to 2880 minutes (48 hours) if not provided. - `currency` string, required: The virtual currency to display to end users. Determines the amount due after conversion. - `returnUrl` string: The URL that the customer will be redirected to if they click **Back to Merchant** button on the payment web page. Must start with `https://`. - `reference` string, required: The custom payment ID to identify the payment within your platform. - `customerId` string, required: The unique ID for the party requesting the payment. If multiple payments for same party are requested, the ID should remain consistent. - `type` 'IN', required: Defines the payment direction. Must be `IN` for incoming payments. - `payInDetails` PayInDetailDto, required: The payment in details, only needed when "type" is IN. - `currency` string, required: Cryptocurrency that the customer must pay in. The address is returned in `redirectURL`. Set this value if you already know the currency your customer uses for pay-ins, to skip the cryptocurrency selection screen. Leave blank to allow customers to choose the currency themselves. For the complete list of available currencies, see [Currencies](https://docs.bvnk.com/bvnk/references/currencies/). - `network` string: Network of the cryptocurrency. We recommend using the `network` parameter instead of `protocol`. For the complete list of available networks, see [Currencies](https://docs.bvnk.com/bvnk/references/currencies/). - `protocol` string: Only used for multiple protocol currencies, like USDT. Will only generate address matching the protocol and no alternatives. **Deprecated**. Use `network` instead. - `currencyOptions` PayRequestCurrencyOptionDto[]: Limits cryptocurrencies and network protocols that customers can use to complete the payment. If omitted, customers can pay with any supported deposit currency. For more information, see [Collect payments](https://docs.bvnk.com/bvnk/use-cases/stablecoin-payments-for-platforms/get-payment/#collect-payments). For supported currencies and protocols, see the [Supported Currencies API](https://api.bvnk.com/api/currency/crypto?max=100&sort=rank&order=asc&allowDeposits=true). - `code` string, required: Cryptocurrency code (for example, `USDT`, `ETH`). - `protocols` string[]: When set, only these network protocols are offered for this currency (for example, `ERC20`, `TRC20`). Omit to allow any supported protocol for the currency. - `complianceDetails` ComplianceDetailDto, required: Specify compliance details about the payment - `requesterIpAddress` string: IPv4/IPv6 address of the requester. Required only if `countryCode` is not provided. - `contactId` string: Identifier of the contact that takes part of the virtual asset transfer. Can be used instead of `partyDetails`. - `partyDetails` PartyDetailDto[], required: Array of compliance information of the entities that take part of the virtual asset transfer. - union: Compliance information of the party related to the virtual asset transfer. - IndividualPartyDetailDto: Compliance information of the Individual related to the virtual asset transfer - `type` string, required: Identifies whether the party detail information belongs to a BENEFICIARY or an ORIGINATOR. Possible values - BENEFICIARY, ORIGINATOR - `entityType` 'INDIVIDUAL' | 'COMPANY', required: Identifies whether the party detail information belongs to an INDIVIDUAL or a COMPANY - `firstName` string, required: First name of the individual (required for INDIVIDUAL entity type) - `lastName` string, required: Last name of the individual (required for INDIVIDUAL entity type) - `dateOfBirth` string, required: Date of birth of the individual - `relationshipType` string, required: Type of the relationship between the BENEFICIARY/ORIGINATOR and the creator of the payment. Possible values - SELF_OWNED, THIRD_PARTY - `countryCode` string, required: The ISO 3166-1-alpha-2 code of the country that the party resides in. Required only if `requesterIpAddress` is not provided. - `regionCode` string, UA-XX: ISO 3166-2:UA code for Ukraine regions. Required only if `countryCode` is `UA`. In this case, submissions with missing or invalid `regionCode` are rejected. For all other countries, the region code is ignored. For the complete list of codes, see [ISO_3166-2:UA](https://www.iso.org/obp/ui/#iso:code:3166:UA). - CompanyPartyDetailDto: Compliance information of the company related to the virtual asset transfer - `type` string, required: Identifies whether the party detail information belongs to a BENEFICIARY or an ORIGINATOR. Possible values - BENEFICIARY, ORIGINATOR - `entityType` 'INDIVIDUAL' | 'COMPANY', required: Identifies whether the party detail information belongs to an INDIVIDUAL or a COMPANY - `legalName` string, required: Name of the company (required for COMPANY entity type) - `relationshipType` string, required: Type of the relationship between the BENEFICIARY/ORIGINATOR and the creator of the payment. Possible values - SELF_OWNED, THIRD_PARTY - `countryCode` string, required: The ISO 3166-1-alpha-2 code of the country that the party resides in. Required only if requesterIpAddress is not provided. - `regionCode` string, UA-XX: ISO 3166-2:UA code for Ukraine regions. Required only if `countryCode` is `UA`. In this case, submissions with missing or invalid `regionCode` are rejected. For all other countries, the region code is ignored. For the complete list of codes, see [ISO_3166-2:UA](https://www.iso.org/obp/ui/#iso:code:3166:UA). - `registrationNumber` string, required: Legal Entity identifier - `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. - `embeddedCustomerDetails` object: Unique customer reference. Must be in the UUID format. - `reference` string, uuid - PayRequestOutDto: Request data for an outgoing crypto payment (`type: OUT`). - `walletId` string, required: Identifier for the debit wallet associated with the transaction. - `merchantId` string: **Deprecated. Don't use, if you specify `walletId`**. Your Merchant ID. You can find it on the Merchant Details page in your account. - `amount` number, required: Payment amount. The minimum cryptocurrency deposit amount to be processed is 5 EUR. - `expiryMinutes` integer: The time period in minutes after which payment expires. Defaults to 2880 minutes (48 hours) if not provided. - `currency` string, required: The virtual currency to display to end users. Determines the amount due after conversion. - `returnUrl` string: The URL that the customer will be redirected to if they click **Back to Merchant** button on the payment web page. Must start with `https://`. - `reference` string, required: The custom payment ID to identify the payment within your platform. - `customerId` string, required: The unique ID for the party requesting the payment. If multiple payments for same party are requested, the ID should remain consistent. - `type` 'OUT', required: Defines the payment direction. Must be `OUT` for outgoing payments. - `twoStep` boolean: Activates a payout that is accepted in two stages. When you create a payout, the funds are reserved, and the quote locks for one hour with the `ACCEPTED` status. Review the quote and approve the payout by calling `PUT /api/v1/pay/{uuid}/confirm/summary` without payload. - `flow` 'EMBEDDED_CRYPTO': Routes the payout through your customer's wallet instead of paying out directly from your wallet. Set to `EMBEDDED_CRYPTO` to send stablecoin payments via your customer's wallet: funds are debited from your pre-funded partner wallet, converted to crypto at BVNK, then paid out as crypto via the customer's wallet to the destination address. All steps are automated. When `flow` is `EMBEDDED_CRYPTO`, remember to add `embeddedCustomerDetails`. In `walletId`, specify your pre-funded partner wallet. If omitted, the payout is created as a standard payout from your wallet. For more information, see [Send stablecoin payments via customer's wallet](/bvnk/use-cases/stablecoin-payments-for-platforms/send-stablecoin-via-customers-wallet). - `fees` object: Customer fee to be charged for the transaction. Customer fees are optional charges that can be added only to outgoing payments for your customers. These fees are separate from the transaction amount and transaction fees, and are collected from the customer's wallet. For more information, refer to [Customer fees](https://docs.bvnk.com/bvnk/get-started/charge-customer-fees). - `customerFee` object: Details of the customer fee to be applied to the transaction. - `currency` string, required: The three-letter ISO currency code of the customer fee. This should match the currency of the transaction and must have a corresponding [fee wallet configured](https://docs.bvnk.com/bvnk/api-explorer/endpoints/set-customer-fee-wallet). - `amount` number, required: The amount of the customer fee to be charged. This is a fixed fee per transaction. Ensure the customer's wallet has sufficient funds to cover this fee in addition to the transaction amount. - `payOutDetails` PayOutDetailDto: Crypto destination details: the gateway code, currency, address, and network, plus a tag where the currency requires one. - `code` string, required: Gateway to be used. Currently, only 'crypto' is supported. - `currency` string, required: Currency code, in which the payout needs to be made. - `address` string, required: Address to which funds will be withdrawn. BVNK strictly enforces the [EIP-55](https://www.binance.com/en/square/post/8436113423258) checksum standard for mixed-case Ethereum addresses in Ethereum Virtual Machine (EVM) networks. If the casing doesn't exactly match the checksum, the address is considered invalid. Make sure that the `0x` prefix is lowercase and use one of the following formats: - All uppercase: `0xCCC2D224ADDEC8AA7A54BB22C7D4AC2D8ACA91BE` - All lowercase: `0xccc2d224addec8aa7a54bb22c7d4ac2d8aca91be` - `tag` string: Tag of the payment destination. This field must not be empty when the `paidCurrency` currency value is `XRP`. - `network` string, required: Network of the cryptocurrency. We recommend using the `network` parameter instead of `protocol`. For the complete list of available networks, see [Currencies](https://docs.bvnk.com/bvnk/references/currencies/). - `protocol` string: Only used for multiple protocol currencies, like USDT. Will only generate address matching the protocol and no alternatives. **Deprecated**. Use `network` instead. - `complianceDetails` ComplianceDetailDto, required: Specify compliance details about the payment - `requesterIpAddress` string: IPv4/IPv6 address of the requester. Required only if `countryCode` is not provided. - `contactId` string: Identifier of the contact that takes part of the virtual asset transfer. Can be used instead of `partyDetails`. - `partyDetails` PartyDetailDto[], required: Array of compliance information of the entities that take part of the virtual asset transfer. - union: Compliance information of the party related to the virtual asset transfer. - IndividualPartyDetailDto: Compliance information of the Individual related to the virtual asset transfer - `type` string, required: Identifies whether the party detail information belongs to a BENEFICIARY or an ORIGINATOR. Possible values - BENEFICIARY, ORIGINATOR - `entityType` 'INDIVIDUAL' | 'COMPANY', required: Identifies whether the party detail information belongs to an INDIVIDUAL or a COMPANY - `firstName` string, required: First name of the individual (required for INDIVIDUAL entity type) - `lastName` string, required: Last name of the individual (required for INDIVIDUAL entity type) - `dateOfBirth` string, required: Date of birth of the individual - `relationshipType` string, required: Type of the relationship between the BENEFICIARY/ORIGINATOR and the creator of the payment. Possible values - SELF_OWNED, THIRD_PARTY - `countryCode` string, required: The ISO 3166-1-alpha-2 code of the country that the party resides in. Required only if `requesterIpAddress` is not provided. - `regionCode` string, UA-XX: ISO 3166-2:UA code for Ukraine regions. Required only if `countryCode` is `UA`. In this case, submissions with missing or invalid `regionCode` are rejected. For all other countries, the region code is ignored. For the complete list of codes, see [ISO_3166-2:UA](https://www.iso.org/obp/ui/#iso:code:3166:UA). - CompanyPartyDetailDto: Compliance information of the company related to the virtual asset transfer - `type` string, required: Identifies whether the party detail information belongs to a BENEFICIARY or an ORIGINATOR. Possible values - BENEFICIARY, ORIGINATOR - `entityType` 'INDIVIDUAL' | 'COMPANY', required: Identifies whether the party detail information belongs to an INDIVIDUAL or a COMPANY - `legalName` string, required: Name of the company (required for COMPANY entity type) - `relationshipType` string, required: Type of the relationship between the BENEFICIARY/ORIGINATOR and the creator of the payment. Possible values - SELF_OWNED, THIRD_PARTY - `countryCode` string, required: The ISO 3166-1-alpha-2 code of the country that the party resides in. Required only if requesterIpAddress is not provided. - `regionCode` string, UA-XX: ISO 3166-2:UA code for Ukraine regions. Required only if `countryCode` is `UA`. In this case, submissions with missing or invalid `regionCode` are rejected. For all other countries, the region code is ignored. For the complete list of codes, see [ISO_3166-2:UA](https://www.iso.org/obp/ui/#iso:code:3166:UA). - `registrationNumber` string, required: Legal Entity identifier - `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. - `embeddedCustomerDetails` object: The embedded customer on behalf of which the payout is initiated. Required when `flow` is `EMBEDDED_CRYPTO`. - `reference` string, uuid, required: Unique BVNK-generated customer reference in the UUID format. Identifies the customer whose wallet the payout is routed through. ## Response `200` OK - SummaryPaymentDto: Contains all the information about a summary payment object returned. - `uuid` string: Unique identifier for the merchant payment. - `merchantDisplayName` string: The display name for the merchant payment. - `walletId` string: Your wallet's ID. - `dateCreated` integer: The date and time, encoded into UNIX epoch timestamps. - `expiryDate` integer: The date and time, encoded into UNIX epoch timestamps. - `quoteExpiryDate` integer: Expiration date and time, encoded into UNIX epoch timestamps. - `acceptanceExpiryDate` integer: Date and time, encoded into UNIX epoch timestamps. - `quoteStatus` string - `reference` string: Custom payment reference ID to tie the payment to your customer. - `type` 'IN' | 'OUT': Defines whether a payment in or payment out. - `subType` 'merchantPayIn' | 'merchantPayOut' | 'merchantRefund': Payment sub type. - `status` 'PENDING' | 'PROCESSING' | 'CANCELLED' | 'COMPLETE' | 'UNDERPAID' | 'OVERPAID' | 'EXPIRED': The payment status. - `displayCurrency` PayAmountsDto: Contains the type of currency, amount to be paid, and amount received. - `currency` string: The currency acronym. - `amount` number: The amount to be paid. - `actual` number: The actual amount received. - `walletCurrency` PayAmountsDto: Contains the type of currency, amount to be paid, and amount received. - `currency` string: The currency acronym. - `amount` number: The amount to be paid. - `actual` number: The actual amount received. - `paidCurrency` PayAmountsDto: Contains the type of currency, amount to be paid, and amount received. - `currency` string: The currency acronym. - `amount` number: The amount to be paid. - `actual` number: The actual amount received. - `feeCurrency` PayAmountsDto: Contains the type of currency, amount to be paid, and amount received. - `currency` string: The currency acronym. - `amount` number: The amount to be paid. - `actual` number: The actual amount received. - `displayRate` ExchangeRateDto: Contains exchange rate information to convert from base currency to counter currency. - `base` string: The base currency acronym. - `counter` string: The counter currency acronym. - `rate` number: The exchange rate - `exchangeRate` ExchangeRateDto: Contains exchange rate information to convert from base currency to counter currency. - `base` string: The base currency acronym. - `counter` string: The counter currency acronym. - `rate` number: The exchange rate - `address` CryptoAddressDto: Payment address details - `address` string: The crypto address to send funds to - `tag` string: This is a payment destination tag. This fields isn't null when the paidCurrency currency value is XRP. - `network` string: The network of the address. We recommend using the `network` parameter instead of `protocol`. - `protocol` string: The protocol behind a currency, 'ERC20' or 'TRC20'. **Deprecated**. Use `network` instead. - `uri` string: The destination address URI for QR code - `alternatives` AlternativeAddressDto[]: The list of non-default addresses for other tokens - `network` string: The network of the alternative address. We recommend using the `network` parameter instead of `protocol`. - `protocol` string: The protocol behind a currency. Matches currency for native tokens. **Deprecated**. Use `network` instead. - `address` string: The crypto address to send funds to. - `tag` string: This is a payment destination tag. This fields isn't null when the paidCurrency currency value is XRP. - `uri` string: The destination address URI for QR code - `returnUrl` string: The URL that the customer will be redirected to if they click 'Back to Merchant' button on the payment web page. - `redirectUrl` string: The URL to the payment page that you redirect your customers to. - `transactions` GatewayTransactionDto[] - `dateCreated` integer: The date and time, encoded into UNIX epoch timestamps. - `dateConfirmed` integer: The date and time, encoded into UNIX epoch timestamps. - `hash` string: Transaction hash. - `amount` number: Payment amount. - `risk` object - `networkFeeCurrency` string: The currency acronym. - `networkFeeAmount` number: The network fee amount. - `sources` string[]: The list of source addresses, only applicable if payment in. - `displayRate` ExchangeRateDto: Contains exchange rate information to convert from base currency to counter currency. - `base` string: The base currency acronym. - `counter` string: The counter currency acronym. - `rate` number: The exchange rate - `exchangeRate` ExchangeRateDto: Contains exchange rate information to convert from base currency to counter currency. - `base` string: The base currency acronym. - `counter` string: The counter currency acronym. - `rate` number: The exchange rate - `refund` object: The payment this object is a refund of. This should reference the pay in that this refund was created for. - `refunds` object[]: Refunds that have been requested for this payment. This should reference the refund payout for this pay in. - `currencyOptions` CurrencyOptions: The currency options. - `transaction` string: View onchain transactions. - `explorer` string: The explorer to view crypto network - `address` string: View wallet address - `confirmations` integer: Number of confirmations needed. - `networkFeeCurrency` object: Details of the network fee currency. - `currency` string: The currency code for the network fee. - `amount` number: The network fee amount. - `actual` number: The actual network fee amount charged. - `flow` string ## Other responses - `400`: Bad Request - `500`: Unexpected Error ## Changes - **2026-11-06** `c386d436bf2c`: 1 breaking, 1 info - the request property `oneOf[subschema #2: Payout (type: OUT)]/embeddedCustomerDetails/reference` became required - added the new optional request property `oneOf[subschema #2: Payout (type: OUT)]/flow` - **2026-06-16** `97d6c0d2fe2e`: 1 breaking, 17 warning, 3 info - the request's body type changed from `object` to no type - removed the request property `amount` - removed the request property `complianceDetails` - removed the request property `currency` - …17 more [Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/api/v1/pay/summary/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)