COconfirmo
Invoice

Create new Invoice

Creates a new Invoice for the merchant.

post/v3/invoices

Request

  • Base URL
    https://confirmo.net/api
  • URL
    https://confirmo.net/api/v3/invoices
  • Auth
    HTTP bearer

Headers

Payment-Module-Namestring

The name of the payment gateway integration solution (a higher-level payment gateway or plugin which integrates this payment gateway). This header is not meant to be used by direct merchant integrations and replaces the legacy 'X-Payment-Module' header. Only basic letters, numbers, underscore('_'), dash ('-'), dot ('.') and space (' ') are allowed.

Payment-Module-Versionstring

The version of the payment gateway integration solution (a higher-level payment gateway or plugin which integrates this payment gateway). This header is not meant to be used by direct merchant integrations. Only basic letters, numbers, dash ('-'), dot ('.') and space (' ') are allowed.

Request body

customerEmailstring email

E-mail address for the customer notifications. May be required for newly registered merchants.

notifyEmailstring email

E-mail address where merchant notifications will be sent.

notifyUrlstring url

Webhook URL where invoice webhooks will be sent.

referencestring

Any data the merchant wishes to store in the invoice. It might be, for instance, a JSON or any other string identifying the Invoice in the merchant's system.

returnUrlstring

URL where the customer will be redirected after the payment.

Example request

{
  "customerEmail": "customerEmail@email.com",
  "customerProfile": {
    "city": "Springfield",
    "country": "US",
    "postalCode": "90210",
    "profileId": "profile-12345",
    "streetAddress": "123 Main Street",
    "lei": "5493001KJTIIGC8Y1R12",
    "registeredName": "ACME Inc.",
    "registrationNumber": "12345678"
  },
  "invoice": {
    "currencyFrom": "EUR",
    "paymentMethodId": "BITCOIN-BLOCKCHAIN-MAINNET-BTC-CURRENCY"
  },
  "notifyEmail": "orderReceived@yourEShop.com",
  "notifyUrl": "https://yourEShop.com/orderReceived",
  "product": {
    "description": "Small silver computer",
    "name": "Computer"
  },
  "reference": "anything",
  "returnUrl": "https://yourEShop.com/orderReceived",
  "settlement": {
    "currency": "EUR"
  }
}

Response

Invoice successfully created

activeSinceinteger

The time of the Invoice's transition to active state as a Unix timestamp. May be null, if the Invoice has never been in active state.

addressstring

The address where a customer is supposed to send crypto to.

buttonInvoiceIdstring

The ID of a Payment Button, if this Invoice has been created by using one.

closedAtinteger

The time when the Invoice was closed as a Unix timestamp.

confirmationsinteger

The number of confirmations.

confirmingSinceinteger

The time of the Invoice's transition to confirming state as a Unix timestamp. May be null, if the Invoice has never been in the confirming state.

createdAtinteger

The time when the Invoice was created as a Unix timestamp.

cryptoUristring

Standardized URI for a crypto payment. It is also used in a payment QR code. Contains at least protocol, address and remaining amount to be paid.

customerEmailstring

The email address to which email notifications for the customer will be sent.

emailInvoiceIdstring

The ID of an Email Invoice, if this Invoice has been created by using one.

errorSinceinteger

The time of the Invoice's transition to error state as a Unix timestamp. May be null, if the Invoice has never been in error state.

expiredSinceinteger

The time of the Invoice's transition to expired state as a Unix timestamp. May be null, if the Invoice has never been in expired state.

feenumber

The fee of the Invoice.

idstring

The Invoice ID.

networkFeenumber

The network fee.

notifyEmailstring

The e-mail address where the e-mail notifications will be sent. The maximum length is 512 characters.

notifyUrlstring

The URL where webhooks will be POSTed.

overUnderPaidAmountnumber

The difference of requested and received amount. Can be positive or negative.

paidSinceinteger

The time when the Invoice acquired the paid status as a Unix timestamp. May be null, if the Invoice has never been in paid state.

paymentMethodIdstring

Identifies the blockchain network and the asset the payment is made in. Null until the payment method is fixed — either by the end customer on the checkout page, or up-front by the merchant through the creation request's 'paymentMethodId'. Values are the 'id' values returned by GET /api/v3/crypto-payment-methods.

pendingVerificationSinceinteger

The time of the Invoice's transition to pending verification state as a Unix timestamp. May be null, if the Invoice has never been in pending verification state.

preparedSinceinteger

The time of the Invoice's transition to prepared state as a Unix timestamp.

referencestring

Any data the merchant wishes to store in the Invoice. It might be, for instance, a JSON or any other string identifying the invoice in the merchant's system. The maximum length is 512 characters.

refundLinkstring uri

The URL of the refund link.

requiredConfirmationsinteger

The number of required confirmations for the Invoice to gain the paid status.

requiredConfirmationsToRefundinteger

The number of required confirmations for refunds to be allowed.

resolvedByEmailstring

Email (or other identifier) of the one responsible for manual resolve.

resolvedManuallyboolean required

Flag saying whether invoice was resolved manually (refund, take)

returnUrlstring

The URL where the customer will be redirected after the payment. The maximum length is 512 characters.

status'prepared' | 'pending_verification' | 'active' | 'confirming' | 'paid' | 'expired' | 'error' | 'blocked'

Please note that invoices that transition from status 'prepared' directly to 'expired' (i.e. those which were never activated) become subject of data purging after a retention period (e.g. a year). An invoice in status 'paid' can still move to 'blocked' when a later compliance check flags its payment.

subscriptionIdstring

Deprecated. Always null; subscriptions are now standalone feature

timeoutTimeinteger

The time of the Invoice's expiration as a Unix timestamp.

unhandledExceptionsboolean

It is true if the payment gateway owes some funds to the customer or the customer has not paid the whole customer amount.

urlstring uri

The URL of the Invoice's public view for the customers.

versioninteger

Monotonic version of the invoice; the client discards any WebSocket payload whose version is not greater than the last applied one (ordering guard).

Example response

{
  "activeSince": 1506080071,
  "address": "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy",
  "buttonInvoiceId": "paby8ngx1eox",
  "closedAt": 1506080071,
  "confirmingSince": 1506080071,
  "createdAt": 1506080071,
  "cryptoTransactions": [
    {
      "confirmations": 6,
      "createdAt": 1594376981,
      "sourceAddresses": [
        "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
        "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy"
      ],
      "txid": "4f13bc54e8df1620f98934078caaa59c7b480f3ed64e9838f5af519f311bb0b1",
      "updatedAt": 1594376981
    }
  ],
  "cryptoUri": "litecoin:mnLU9vBK7L1WY6JNnGYY...Jdjwfnti4Cu9xz?amount=1.00000000",
  "customerAmount": {
    "amount": 1000,
    "currency": "EUR"
  },
  "customerEmail": "customerEmail@email.com",
  "emailInvoiceId": "emi4og3r6g3w",
  "errorSince": 1506080071,
  "expiredSince": 1506080071,
  "flags": {
    "overpaymentResolvable": true
  },
  "id": "invl8em3zdkr",
  "layer2Attributes": {
    "protocolName": "LIGHTNING"
  },
  "merchantAmount": {
    "amount": 1000,
    "currency": "EUR"
  },
  "notifyEmail": "orderReceived@yourEShop.com",
  "notifyUrl": "https://yourEShop.com/orderReceived",
  "paid": {
    "currency": "LTC"
  },
  "paidSince": 1506079178,
  "paymentMethodId": "BITCOIN-BLOCKCHAIN-MAINNET-BTC-CURRENCY",
  "pendingVerificationSince": 1506080071,
  "preparedSince": 1506080071,
  "product": {
    "description": "Small silver computer",
    "name": "Computer"
  },
  "rate": {
    "currencyFrom": "EUR",
    "currencyTo": "LTC"
  },
  "reference": "string {'customer_mail': 'customer@example.com'}",
  "refundLink": "https://pay.confirmo.com/public/permit-refund/aW52MDJleTI0MWdrNGE5MmFjNGRkYTE1YjQ5ZDI3MzA4NzBhYWEzYjc5YzE=?refundEmail=test@bitcoin.com&merchantId=dfjeivkdienmv",
  "refunds": [
    {
      "address": "3Bp6GX52uY574Uq7k6opCx1zHd5hVhAXHq",
      "createdAt": 1594376981,
      "id": "refz0gr3qgx9",
      "notifyEmail": "test@test.com",
      "refundedAt": 1594376981,
      "substatus": "SCREENING_IN_PROGRESS",
      "txid": "4f13bc54e8df1620f98934078caaa59c7b480f3ed64e9838f5af519f311bb0b1",
      "updatedAt": 1594376981
    }
  ],
  "requiredConfirmations": 2,
  "requiredConfirmationsToRefund": 6,
  "resolvedByEmail": "user@mail.ex",
  "resolvedManually": true,
  "returnUrl": "https://yourEShop.com/orderReceived",
  "settlement": {
    "createdAt": 1561363200,
    "currency": "EUR",
    "id": "setv9e1qxgz8"
  },
  "settlementAmount": {
    "amount": 1000,
    "currency": "EUR"
  },
  "takeInfo": {
    "customerCurrency": "LTC",
    "expiration": 1552987955,
    "expirationDuration": 120,
    "offeredSettlementAmount": 3198,
    "settlementCurrency": "EUR",
    "taken": true,
    "takenAt": 1552987719
  },
  "timeoutTime": 1506080071,
  "unhandledExceptions": true,
  "url": "https://pay.confirmo.com/public/invoice/NOLvQIt2na6kfXBb?m=dfjeivkdienmv",
  "version": 42
}

Changes

No recorded changes to this operation across all 1 revision of this API.