/merchant/invoicesCreate an Invoice
postMerchantInvoicesV2https://a-api.coinpayments.net/api/v2/merchant/invoicesRequest
Body schema · JSONRequest
currencystringCurrency of the invoice items and amount
customIdstringnullablethe API caller provided external ID for the item. Appears on the Merchant dashboard and reports only.
skustringnullablethe stock keeping unit (SKU) of the item
namestringthe name or title of the item
descriptionstringnullablethe detailed description of the item
valueintegerthe quantity of the item. Must be greater than 0 and less than 999,999,999. defaults to 1 if not provided.
int32typestringDefines the types of quantities applicable to a line item in the CoinPayments merchant system. It categorizes the quantity as either a measure of time or a specific count.
hoursquantityoriginalAmountstringnullablethe original total price of the item if CoinPayments.Services.Merchants.Dtos.LineItemV2Dto.Amount represents a discounted price
amountstringthe subtotal price of the item (note: this is not a per unit price but the total price for the total quantity)
taxstringnullablethe total taxes charged on this item
subtotalstringthe subtotal for all items, required if the request includes `invoice.items[]` and must be equal to the sum of all `(invoice.items[].amount)` for all items.
shippingstringnullablethe optional shipping fee for all items within the invoice
handlingstringnullablethe optional handling fee for all items within the invoice
taxTotalstringnullablethe total taxes charged on the invoice, required if the request includes `invoice.items[]` with taxes and must be equal to the sum of all `(invoice.items[].tax)` for all items.
discountstringnullablethe optional discount for all items within the invoice
totalstringThe total amount associated with the invoice, encompassing all charges, fees, and adjustments.
isEmailDeliverybooleanindicates if invoice will be email delivered
tostringnullablethe email `to` field, multiple addresses separated by semicolons
ccstringnullablethe email `cc` field, multiple addresses separated by semicolons
bccstringnullablethe email `bcc` field, multiple addresses separated by semicolons
dueDatestringnullableoptional due date to be shown on the invoice
date-timeinvoiceDatestringnullableoptional custom invoice date if not the created date of the invoice, invoices with a future date will be scheduled
date-timedraftbooleannullableflag indicating whether this is a draft invoice
clientIdstringnullablethe id of the client creating this invoice (optional)
invoiceIdstringnullablethe optional API caller provided external invoice number. Appears in screens shown to the Buyer and emails sent.
companyNamestringnullablethe name of the buyer's company
firstNamestringnullablethe given, or first, name
lastNamestringnullablethe surname or family name. Required when the party is a person.
emailAddressstringnullablethe email address of the buyer
customer@example.comphoneNumberstringnullablethe phone number
address1stringnullablethe first line of the address. For example, number or street.
123 Fake streetaddress2stringnullablethe second line of the address. For example, suite or apartment number.
Apartment 42address3stringnullablethe third line of the address, if needed. For example, a street complement for Brazil, direction text such as 'next to Walmart', or a landmark in an Indian address.
provinceOrStatestringnullablethe highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, `CA` instead of `California` - UK: county - US: state - Canada: province - Japan: prefecture - Switzerland: kanton
BCcitystringnullablethe city, town or village
VancouversuburbOrDistrictstringnullablethe neighborhood, suburb or district. - Brazil: Suburb, bairoo, or neighborhood - India: Sub-locality or district, Street name information is not always available but a sub-locality or district can be a very small area
countryCodestringnullablethe two-character IS0-3166-1 country code
CApostalCodestringnullablethe postal code, which is the zip code or equivalent.
descriptionstringnullablethe purchase description, can be provided instead of a list of `items`
methodstringnullablethe shipping method
companyNamestringnullablethe company name of the party to ship the items to
firstNamestringnullablethe given, or first, name
lastNamestringnullablethe surname or family name. Required when the party is a person.
emailAddressstringnullablethe email address of the party to ship the items to
emailExamplecustomer@example.comphoneNumberstringnullablethe phone number
address1stringnullablethe first line of the address. For example, number or street.
123 Fake streetaddress2stringnullablethe second line of the address. For example, suite or apartment number.
Apartment 42address3stringnullablethe third line of the address, if needed. For example, a street complement for Brazil, direction text such as 'next to Walmart', or a landmark in an Indian address.
provinceOrStatestringnullablethe highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format for postal delivery. For example, `CA` instead of `California` - UK: county - US: state - Canada: province - Japan: prefecture - Switzerland: kanton
BCcitystringnullablethe city, town or village
VancouversuburbOrDistrictstringnullablethe neighborhood, suburb or district. - Brazil: Suburb, bairoo, or neighborhood - India: Sub-locality or district, Street name information is not always available but a sub-locality or district can be a very small area
countryCodestringnullablethe two-character IS0-3166-1 country code
CApostalCodestringnullablethe postal code, which is the zip code or equivalent.
hasDatabooleanrequireBuyerNameAndEmailbooleannullableflag indicating whether a buyer name and email are required, they will be requested at checkout if not provider by the caller. The CoinPayments.Api.Models.Merchant.CreateMerchantInvoiceRequestV2Dto.BuyerDataCollectionMessage will be displayed to the buyer when prompted.
buyerDataCollectionMessagestringnullablethe message to display when collecting buyer user data
notesstringnullablenotes for the merchant only, these are not visible to the buyers
notesToRecipientstringnullableany additional information to share with the buyer about the transaction
termsAndConditionsstringnullableany terms and conditions, e.g. a cancellation policy
showAddressbooleanIndicates whether the address should be shown on the invoice. Default is don't show if not provided.
showEmailbooleanIndicates whether the email should be shown on the invoice. Default is show the email if not provided.
showPhonebooleanIndicates whether the phone should be shown on the invoice. Default is don't show if not provided.
showRegistrationNumberbooleanIndicates whether the business registration number should be shown on the invoice. Default is don't show if not provided.
showTaxIdbooleanSpecifies whether the tax ID should be displayed on the invoice. Defaults to not shown if not explicitly set.
additionalInfostringnullableMiscellaneous information to be displayed on the invoice, such as business hours or other info specific to the invoice
customDataobjectnullableany custom data the caller wishes to attach to the invoice which will be sent back in notifications
integrationstringnullablethe integration from which the invoice was created
hostnamestringnullablethe hostname on which the invoice was created
poNumberstringnullableMerchant's invoice number. Сan store any string. If the field is not filled in, a sequence number will be generated. Must be unique per merchant
notificationsUrlstringthe url to which to POST webhook notifications to
urinotificationsstring[]the types of notifications to send to this endpoint
invoiceCreatedinvoicePendinginvoicePaidinvoiceCompletedinvoiceCancelledinvoiceTimedOutinvoicePaymentCreatedinvoicePaymentTimedOutfromCurrencystringThe buyer selected currency
toCurrencystringthe currency of the wallet or address into which to payout to
addressstringthe external address into which to pay out
frequencystringnormalasSoonAsPossiblehourlynightlyweeklyuseCoinReservationbooleanIndicates whether the invoice will use coin reservation for FIAT currency during transaction processing.
paymentCurrencystringnullableCreate payment address for currency.
refundEmailstringthe email address to which to send refund instructions to in case there is a problem with the invoice payment
hideShoppingCartbooleanFlag for hiding icon on the checkout app
affiliateIdstringnullableIdentifier of the affiliate associated with the invoice, if applicable
uuidisSimpleQRbooleannullableIf IsSimpleQR is true, the checkout app generates a QR code with only the address. Otherwise, the QR code includes the address, currency, and amount.
successUrlstringnullablethe url to redirect to once an invoice is successfully paid
cancelUrlstringnullablethe url to redirect to if payment of an invoice fails (e.g. expired) or is cancelled by the user
Responses
200 · 401 · 403Response to an invoice creation request
idstringThe id of the created invoice
linkstringThe link to the created invoice
checkoutLinkstringThe link to the checkout app
paymentIdstringthe id of the payment
expiresstringthe timestamp when the payment expires and new payments will no longer be accepted
date-timeidstringthe unique id of the currency on the CoinPayments platform
1235typestringType of currency
cryptotokenfiatsymbolstringticker symbol for the currency. For fiat currencies this is the three character (ISO-4217) currency code, and for crypto currencies their multi-character symbol.
BTCnamestringthe name of the currency, e.g. 'United States Dollar' or 'Bitcoin'
BitcoinimageUrlstringnullableLink to a CoinPayments hosted image for a currency in a SVG format
decimalPlacesintegerthe number of digits after the decimal separator, e.g. 2 for USD, 8 for BTC, 0 for JPY
int32rankintegerthe relative ordering/ranking of this currency to the other supported currencies on the CoinPayments platform
int32statusstringThe status of the currency on the CoinPayments platform
activeunderMaintenancedeletedcapabilitiesstring[]nullablethe capabilities of the currency on the CoinPayments platform
paymentssingleSigAccountspooledAccountsutxoconversiononRampoffRampwebsitesstring[]nullablethe websites for the currency
explorersstring[]nullablethe explorers for the currency (if crypto or a token)
requiredConfirmationsintegerThe required number of confirmations needed to be received to treat transactions related to this currency as confirmed
int64isEnabledForPaymentbooleanWhether currency is enabled as a payment option for invoices and payment buttons
isDisabledbooleanflag indicating whether this currency is currently unavailable (e.g. node or services down)
amountstringthe total amount due to pay the remainder of the invoices balance in this currency
approximateNetworkAmountstringRepresents the approximate amount of the payment in network-native currency terms. This property provides a network-based estimation converted into a string format.
remainingAmountstringThe remaining amount to be paid for the current invoice in the specified CoinPayments.Api.Models.Merchant.InvoicePaymentCurrencyV2Dto.Currency.
refundEmailstringThe email address associated with the recipient to which any refunds should be sent.
idstringthe unique id of the currency on the CoinPayments platform
1235typestringType of currency
cryptotokenfiatsymbolstringticker symbol for the currency. For fiat currencies this is the three character (ISO-4217) currency code, and for crypto currencies their multi-character symbol.
BTCnamestringthe name of the currency, e.g. 'United States Dollar' or 'Bitcoin'
BitcoinimageUrlstringnullableLink to a CoinPayments hosted image for a currency in a SVG format
decimalPlacesintegerthe number of digits after the decimal separator, e.g. 2 for USD, 8 for BTC, 0 for JPY
int32rankintegerthe relative ordering/ranking of this currency to the other supported currencies on the CoinPayments platform
int32statusstringThe status of the currency on the CoinPayments platform
activeunderMaintenancedeletedcapabilitiesstring[]nullablethe capabilities of the currency on the CoinPayments platform
paymentssingleSigAccountspooledAccountsutxoconversiononRampoffRampwebsitesstring[]nullablethe websites for the currency
explorersstring[]nullablethe explorers for the currency (if crypto or a token)
requiredConfirmationsintegerThe required number of confirmations needed to be received to treat transactions related to this currency as confirmed
int64isEnabledForPaymentbooleanWhether currency is enabled as a payment option for invoices and payment buttons
amountstringthe amount due to be paid in this currency
remainingAmountstringRepresents the remaining amount to be paid for an invoice, expressed as a string.
addressstringthe raw payment address
biP21stringnullablethe BIP21 payment code, if available
expiresstringthe timestamp when the payment expires and new payments will no longer be accepted
date-time