Client Webhook Payload
This is the webhook payload sent to your server once you have configured client webhooks.
The top-level type field is the event type; the nested invoice.state and invoice.payments[].state fields carry the invoice status and the per-payment status.
idstringnullablethe CoinPayments id for the invoice
typestringThe event type that triggered this webhook, in PascalCase. The matching subscription values (used when registering the webhook) are camelCase.
InvoiceCompletedEnumInvoiceCreatedInvoicePendingInvoicePaidInvoiceCompletedInvoiceCancelledInvoiceTimedOutInvoicePaymentCreatedInvoicePaymentTimedOuttimestampstringDate and time of producing the event.
invoiceIdstringinvoice number assigned by the merchant
idstringinvoice id assigned by the system
userIdstringthe id of the merchant creating this invoice
merchantIdstringthe id of the merchant creating this invoice
merchantClientIdstringthe id of the client API integration creating this invoice
invoiceNumberstringinvoice number assigned by the merchant
invoiceNumberSuffixstringsuffix of the invoice number assigned by the merchant
createdAtstringtimestamp when invoice was created
invoiceDatestringdate when invoice was issued
dueDatestringdate when invoice is due to be paid
descriptionstringdescription of the invoice
expiresDatestringdate when invoice expires
additionalProp1anyMerchant-defined custom property.
additionalProp2anyMerchant-defined custom property.
additionalProp3anyMerchant-defined custom property.
notesstringnotes for the merchant only, these are not visible to the buyers
notesToRecipientstringany additional information to share with the buyer about the transaction
buyerDataCollectionMessagestringthe message to display when collecting buyer user data
termsAndConditionsstringany terms and conditions, e.g. a cancellation policy
integrationstringintegration name
hostnamestringserver name of the integration API
poNumberstringcompanyNamestringname of the buyer's company
emailstringbuyer's email address
firstNamestringbuyer's first name
lastNamestringbuyer's last name
phoneNumberstringbuyer's phone number
address1stringmain address
address2stringadditional address data
address3stringadditional address data
provinceOrStatestringProvince or state of the buyer
citystringcity of the buyer
suburbOrDistrictstringSuburb or district of the buyer
countryCodestringcountry code
postalCodestringpostal code
methodstringShipment method
companyNamestringreceiver company name
firstNamestringfirst name of the receiver
lastNamestringlast name of the receiver
emailAddressstringreceiver email address
phoneNumberstringreceiver phone number
address1stringmain address
address2stringadditional address data
address3stringadditional address data
provinceOrStatestringProvince or state of the receiver
citystringcity of the receiver
suburbOrDistrictstringSuburb or district of the receiver
countryCodestringcountry code
postalCodestringpostal code
amountstringpurchase cost
customIdstringid of the purchase item in merchant's system
descriptionstringdescription of the purchase item
namestringname of purchase item
originalAmountstringpurchase item cost
quantityintegerquantity of the purchase items bought
skustringpurchase item SKU number
taxstringtax amount
typestringpurchase item type
showAddressboolean= falseindicates whether to show merchant's address on the invoice
showPhoneboolean= falseindicates whether to show merchant's phone number on the invoice
showRegistrationNumberboolean= falseindicates whether to show merchant's registration number on the invoice
showEmailboolean= falseindicates whether to show merchant's email address on the invoice
additionalInfostringindicates whether to show any other merchant's additional info on the invoice
tostringto email address. The value can take multiple addresses separated by semicolons
ccstringfield to add multiple recipients separated by semicolons
bccstringbcc field similar to `cc` field except that other recipients won't be able to see that someone else has been sent a copy of the email
currencyIdintegerid of the currency in the system
subtotalstringsubtotal amount of the purchase
shippingTotalstringshipping amount of the purchase
handlingTotalstringhandling service amount of the purchase
discountTotalstringdiscount amount of the purchase
taxTotalstringtax amount of the purchase
totalstringtotal amount of the purchase
statestringcurrent status of the invoice, in PascalCase. See Invoice Statuses for the full lifecycle.
UnpaidPendingPaidScheduledForPayoutCompletedCancelledTimedOutrequireBuyerNameAndEmailbooleanif buyer's email and name required
sendPaymentCompleteEmailNotificationbooleanif sending of the payment completion email required
isPosbooleanif point of sale required
canceledAtintegertime when invoice is canceled
completedAtintegertime when invoice is completed
confirmedAtintegertime when invoice is confirmed
idstringpayment id
invoiceIdstringinvoice id
createdAtintegertime when payment is created
expiresAtintegertime when payment expires
cancelledAtintegertime when invoice is canceled
detectedAtintegertime when payment is detected in mempool or on chain
pendingAtintegertime when invoice is identified as pending
confirmedAtintegertime when payment is confirmed
completedAtintegertime when payment is completed
scheduledAtintegertime when invoice is scheduled for sending out
statestringstatus of this individual payment, in PascalCase. This is the per-payment lifecycle and is distinct from the invoice-level state above.
CreatedDetectedPendingConfirmedScheduledForPayoutCompletedCancelledWaitingRefundTimedOutWaitingRefundTimedOutRefundProcessedCancelledRefundProcessedRefundedrefundedAtintegertime when payment is refunded
refundEmailstringemail for making refund
isGuestbooleanif payer is a system guest or a registered user
idintegerfiat currency id
smartContractstringcurrency smart contract. Default - null
paymentSubTotalInNativeCurrencyintegeramount of payment in the default fiat currency
merchantMarkupOrDiscountInNativeCurrencyintegermarkup or discount amount to the payment amount in the default fiat currency
coinPaymentsFeeintegeramount of fee charged from buyer by CoinPayments in the default fiat currency
networkFeeintegeramount of the network fee charged from buyer in the default fiat currency
conversionFeeintegeramount of conversion fee charged from the buyer in the default fiat currency
coinPaymentsFeeintegeramount of fee charged from merchant by CoinPayments in the default fiat currency
networkFeeintegeramount of the network fee charged from merchant in the default fiat currency
conversionFeeintegeramount of conversion fee charged from merchant in the default fiat currency
confirmedAmountInNativeCurrencyintegerconfirmed amount of payment in the default fiat currency
unconfirmedAmountInNativeCurrencyintegerunconfirmed amount of payment in the default fiat currency
idstringwallet id
paymentIdstringpayment id
idintegerpayment currency id
smartContractobjectpayment smart contract details
idintegerpayout currency id
smartContractobjectpayout currency smart contract details
currencyRateFromInvoiceCurrencyintegerrate of the payment currency to the invoice currency
paymentReceiveAddressstringaddress of payment is received
merchantPayoutAddressstringaddress to payout funds to the merchant
merchantPayoutWalletIdstringid of the payout wallet of the merchant
paymentSubTotalstringinvoice amount subtotal
merchantMarkupOrDiscountintegeramount of the discount provided by the merchant for the currency
isConversionbooleanif conversion is required by payout settings of the merchant for the currency of payment
buyerFeeobjectbreakdown of additional fees paid by the buyer
merchantFeeobjectbreakdown of additional fees paid by the merchant
payoutFrequencystringfrequency mode for funds payout set by the merchant
createdAtintegertime when payout is created
codestringerror code
messagestringerror message
Unknown = 0,NegativeRate = 1,PayoutAddressIsNull = 2,PaymentSubTotalIsLessThanMerchantTotalFee = 4,TotalBuyerWillPayIsNegativeOrZero = 8,TotalBuyerWillPayIsLessThanBuyerNetworkFee = 16,TotalMerchantFeeRatioIsMoreThanMaximumRatioSetting = 32,PayoutAmountIsLessThanDust = 64,CurrencyIsNotActive = 128,AmountIsBelowOfConversionLimit = 256,AmountIsAboveOfConversionLimit = 512,UserLimitIsReached = 1024,NotEnoughToActivateRippleAddress = 2048,ConversionPairDoesNotExist = 4096,AddressIsNotValid = 8_192,DoesNotHaveCompletedKyc = 16_384,UnstoppableDomainNotFound = 32_768,UnstoppableDomainNotFoundForCurrency = 65_536,UserWalletIsLocked = 131_072confirmationsintegeramount of confirmations gathered by the payment transaction on chain. Deposits require a specific number of blockchain confirmations to release the funds for payout. Sending goods or crediting funds to the customer prior to receiving the full number of confirmations shall be done at merchant's own risk.
confirmedAmountintegeramount of payment that received necessary amount of confirmation on chain
requiredConfirmationsintegeramount of confirmations required for the payment currency for the transaction to be completed. Deposits require a specific number of blockchain confirmations to release the funds for payout. Sending goods or crediting funds to the customer prior to receiving the full number of confirmations shall be done at merchant's own risk.
unconfirmedAmountintegeramount of payment that was detected on chain but that has not received necessary amount of confirmations yet
assignedFromstringtimestamp from when assignment of the pooled wallet to the hot wallet is valid
assignedUntilstringtimestamp until assignment of the pooled wallet to the hot wallet is valid
completedDatestringtimestamp when assignment of the pooled wallet to the hot wallet is completed
pooledWalletIdstringid of the wallet in the pool of addresses used for payment receipt
expiresAtintegertime when pooled wallet returns to the system pool of addresses
destinationAmountInNativeCurrencyintegerpayment amount without deduction of fees in default fiat currency
payoutAmountToMerchantInNativeCurrencyintegerfinal amount with deduction of fees to be paid out to the merchant in default fiat currency
buyerBlockchainFeeAfterGroupingInNativeCurrencyintegernetwork fee paid by buyer in default fiat currency
merchantBlockchainFeeAfterGroupingInNativeCurrencyintegernetwork fee paid by merchant in default fiat currency
idstringpayout id
invoicePaymentIdstringid of the invoice payment
invoicePaymentHotWalletIdstringid of the hot wallet for receiving invoice payment
createdstringdate and time when payment was created
sentstringdate and time when payment was sent
confirmedstringdate and time when payment was confirmed on chain
failedstringdate and time when payment failure was detected
merchantPayoutWalletIdstringid of the wallet where payout is made for the merchant
merchantPayoutWalletCurrencyIdintegerid of the currency of the wallet used for payout for the merchant
merchantPayoutWalletSmartContractobjectdetails of the smart contract of the currency of the wallet where payout is made for the merchant
merchantPayoutAddressstringid of the merchant external payout address
payoutAmountToMerchantintegeramount to be paid out to merchant to the payout address
blockchainTransactionIdstringid of the transaction on blockchain for sending paid out amount to the external merchant's address
statestringcurrent state of the payment
batchIdstringid of the transaction batch within which CoinPayments sends paid out amount to the merchant's external address
destinationAmountintegeramount of payment without deduction of fees
transactionIdintegerpayout transaction id in CoinPayments system
buyerBlockchainFeeAfterGroupingintegernetwork fee paid by buyer
merchantBlockchainFeeAfterGroupingintegernetwork fee paid by merchant
payoutAmountInNativeCurrencyintegeramount that was refunded in the default fiat currency
payoutNetworkFeesInNativeCurrencyintegeractual amount of blockchain network fees for putting refund transaction on chain in the default fiat currency
estimatedNetworkFeesInNativeCurrencyintegerestimated amount of blockchain network fees for putting refund transaction on chain in the default fiat currency
isActivebooleanif payment is active or expired
currencyIdstringthe currency id of the wallet or address into which to payout to
addressstringthe external address into which to pay out
walletIdstringid of the wallet into which to payout to (used if no address is available for the merchant)
partialAcceptAvailablebooleanif accepting partial payment is possible