# Invoices

With the Apirone API, you can issue invoices that allow for seamless payments made by customers in crypto Accounts. In the requests, a customer can see all the invoice details, as well as check its status, callback information and history. The invoice can contain any data parameters which the customer would like to see in the invoice. These are predefined fields that the Apirone service added to the invoice, for example, merchant, URL, and price.

# Create Invoice

Generates an invoice. Customer should have the Apirone account to create invoice.

# Request

  • HTTP Method: POST
  • Content Type: application/json
  • URL: https://apirone.com/api/v2/accounts/{AccountID}/invoices

# Request example:

curl -X POST 'https://apirone.com/api/v2/accounts/apr-e729d9982f079fa86b10a0e3aa6ff37b/invoices' \
-H 'Content-Type: application/json' \
-d '{
    "amount": 25000,
    "currency": "btc",
    "lifetime": 3600,
    "callback_url": "http://example.com",
    "user-data": {
        "merchant": "SHOP",
        "url": "https://exampleshop.com",
        "price": {
            "currency": "usd",
            "amount": 100
            }},
    "linkback": "http://linkback.com"
    }'
Parameter Type Description Required
currency string Currency type (any cryptocurrency supported by service)
amount integer Amount for the checkout in the selected currency of the invoice object. Also you may create invoices without fixed amount. The amount is indicated in minor units
lifetime integer Duration of invoice validity (indicated in seconds)
expire string Invoice expiration time in ISO-8601 (opens new window) format, for example, 2022-02-22T09:00:30. If both parameters are specified: lifetime and expire, then the parameter expire will take precedence
callback-url string Callback URL used for invoice status updates notifications. More information about invoice callback see here
user-data object You can specify any data that you would like to see in the invoice. And there are some fields used for invoice representation, such as merchant, url, price, etc.
linkback string The customer will be redirected to this URL after the payment is completed

Object user-data consist on:

Parameter Type Description
merchant string Merchant name. Used as the invoice title
url string Merchant url
price object Used in the invoice to display currency and amount in fiat

# Example of user-data object

		"user-data": {
        "merchant": "SHOP",
        "url": "http://exampleshop.com",
        "price": {
            "currency": "usd",
            "amount": 100
        }
    }

With each changing invoice status the Apirone service notifies the specified callback URL. At the time expiration, the invoice status switches to expired, and our service sends a callback. Subsequent actions with this invoice do not call a callback. In this case, all the funds received at the invoice address are processed the same way as with a valid invoice.

# Success Response Reference

  • HTTP Status Code: 200
  • Content Type: application/json
Parameter Type Description
invoice string Invoice Identifier
created string Invoice creation date. Contains the full date in ISO-8601 (opens new window) format, for example, 2022-02-22T09:00:30
account string Account Identifier
currency string Currency type
amount integer Amount in the selected currency
expire string Invoice expiration time in ISO-8601 (opens new window) format, for example, 2022-02-22T09:00:30
address string The generated cryptocurrency address to receive a payment from a customer
callback-url string Callback URL to receive data about the payment
user-data object Some additional information about the invoice
history array Invoice status change history
linkback string The customer will be redirected to this URL after the payment is completed
status string Invoice status. More information see here
invoice-url string Link to the invoice web view

# Response example:

	{
    "invoice": "amr94MKUQCYAzR6c",
    "created": "2022-04-27T12:02:49.375153",
    "account": "apr-e729d9982f079fa86b10a0e3aa6ff37b",
    "currency": "btc",
    "amount": 25000,
    "expire": "2022-04-27T13:02:49.375153",
    "address": "3HfNiiSFfCJsvMD8joofyt3JCV9iy4N8xz",
    "callback-url": "http://example.com",
    "user-data": {
        "merchant": "SHOP",
        "url": "https://exampleshop.com",
        "price": {
            "currency": "usd",
            "amount": 100
        }
    },
    "linkback": "http://linkback.com",
    "status": "created",
    "invoice-url": "https://apirone.com/invoice?id=amr94MKUQCYAzR6c"
	}

# Error response

  • HTTP Status Code: 400 500
  • Content Type: application/json

Playground

# Public Invoice Info

Checks the invoice information and its status.

# Request

  • HTTP Method: GET
  • URL: https://apirone.com/api/v2/invoices/{InvoiceID}
Parameter Type Description Required
InvoiceID string Invoice Identifier

# Request example

curl 'https://apirone.com/api/v2/invoices/amr94MKUQCYAzR6c'

# Success Response Reference

Parameter Type Description
invoice string Invoice Identifier
created string Invoice creation date in ISO-8601 (opens new window) format (for example, 2022-02-22T09:00:30)
currency string Currency type
address string The generated cryptocurrency address to receive a payment from a customer
expire string Invoice expiration time in ISO-8601 (opens new window) format (for example, 2022-02-22T09:00:30)
amount integer Amount for the checkout in the selected currency
user-data object Some specified data in the invoice
status string Invoice status
history array Invoice status change history
linkback string The customer will be redirected to this URL after the payment is completed
invoice-url string Link to the invoice web view

Object history consist on:

Type Description
date string Invoice status change date
status string Invoice status
txid string Identifier of the transaction in the blockchain
amount integer Paid amount

# Invoice Status

Type Description
created Initial state when the invoice is created in the account
paid As soon as the payment is received, the service compares the paid amount with the invoice requested amount. If the paid amount is equal to the amount expected, then the invoice is marked as paid
partpaid Status will be returned for cases when the customer partially paid for the invoice
overpaid Status will be returned, if the payment from a customer exceeds the amount indicated in the invoice
completed When the block with the invoice's transaction is added to the blockchain, the transaction received the required number of confirmations, the invoice gets this status
expired The invoice has got the "expired" status, if the expiration date has arrived

# Response example

	{
    "invoice": "amr94MKUQCYAzR6c",
    "created": "2022-04-27T12:02:49.375153",
    "currency": "btc",
    "address": "3HfNiiSFfCJsvMD8joofyt3JCV9iy4N8xz",
    "expire": "2022-04-27T13:02:49.375153",
    "amount": 25000,
    "user-data": {
        "merchant": "SHOP",
        "url": "https://exampleshop.com",
        "price": {
            "currency": "usd",
            "amount": 100
        }
    },
    "status": "completed",
    "history": [
        {
            "date": "2022-04-27T12:02:49.375153",
            "status": "created"
        },
        {
            "date": "2022-04-27T12:04:24.251921",
            "status": "partpaid",
            "txid": "26cfe85c09e22c423624fd23b2380bce626ea94db6fb5093bfa012e7407f25b1",
            "amount": 19000
        },
        {
            "date": "2022-04-27T12:05:25.241341",
            "status": "paid",
            "txid": "289c24a8804369c0afe9751d00aa0f19449cc05a1b00c37de078612b55821a72",
            "amount": 6000
        },
        {
            "date": "2022-04-27T12:08:25.050088",
            "status": "completed"
        }
    ],
    "linkback": "http://linkback.com",
    "invoice-url": "https://apirone.com/invoice?id=amr94MKUQCYAzR6c"
	}

# Error response

  • HTTP Status Code: 400 500
  • Content Type: application/json

Playground

# Private Invoice Info

The response contains information about the invoice including security-sensitive data (e.g. callback info). Authorization is required.

# Request

  • HTTP Method: GET
  • URL: https://apirone.com/api/v2/accounts/{AccountID}/invoices/{InvoiceID}
Parameter Type Description Required
AccountID string Account Identifier
InvoiceID string Invoice Identifier
transfer-key string Key for accessing protected endpoints *

* transfer-key is required unless access token is applied

# Request example

curl 'https://apirone.com/api/v2/accounts/apr-e729d9982f079fa86b10a0e3aa6ff37b/invoices/amr94MKUQCYAzR6c?transfer-key=82ookirnTwWNXXqFwdOQMVZIamt8s1uT'

# Success Response Reference

Parameter Type Description
account string Account Identifier
invoice string Invoice Identifier
created string Invoice creation date
currency string Currency type
amount integer Amount for the checkout in the specified currency
expire string Invoice expiration time in ISO-8601 (opens new window) format (for example, 2022-02-22T09:00:30)
address string The generated cryptocurrency address to receive a payment from a customer
user-data string Some specified data in invoice
status string Invoice status
history array Changes of the invoice status in history (contains change of the status date and the invoice status)
callback-url string Callback URL
linkback string The customer will be redirected to this URL after payment is completed
invoice-url string Link to the invoice web view

# Response example

	{	"account": "apr-e729d9982f079fa86b10a0e3aa6ff37b",
    "invoice": "amr94MKUQCYAzR6c",
    "created": "2022-04-27T12:02:49.375153",
    "currency": "btc",
    "amount": 25000,
    "expire": "2022-03-13T11:36:37.342134",
    "address": "3HfNiiSFfCJsvMD8joofyt3JCV9iy4N8xz",
    "user-data": {
        "merchant": "SHOP",
        "url": "https://exampleshop.com",
        "price": {
            "currency": "usd",
            "amount": 100
        }
    },
    "status": "completed",
    "history": [
        {
            "date": "2022-04-27T12:02:49.375153",
            "status": "created"
        },
        {
            "date": "2022-04-27T12:04:24.251921",
            "status": "partpaid",
            "txid": "26cfe85c09e22c423624fd23b2380bce626ea94db6fb5093bfa012e7407f25b1",
            "amount": 19000
        },
        {
            "date": "2022-04-27T12:05:25.241341",
            "status": "paid",
            "txid": "289c24a8804369c0afe9751d00aa0f19449cc05a1b00c37de078612b55821a72",
            "amount": 6000
        },
        {
            "date": "2022-04-27T12:08:25.050088",
            "status": "completed"
        }
    ],
    "callback-url": "https://example.com",
    "linkback": "http://linkback.com",
    "invoice-url": "https://apirone.com/invoice?id=amr94MKUQCYAzR6c"
  }

# Error response

  • HTTP Status Code: 400 500
  • Content Type: application/json

Playground

# Invoices List

Shows a list of all invoices in the account. Contains information about each invoice. Authorization is required.

# Request

  • HTTP Method: GET
  • URL: https://apirone.com/api/v2/accounts/{AccountID}/invoices
Parameter Type Description Required
AccountID string Account Identifier
transfer-key string Key for accessing protected endpoints *

* transfer-key is required unless access token is applied

# Request example

curl 'https://apirone.com/api/v2/accounts/apr-e729d9982f079fa86b10a0e3aa6ff37b/invoices?transfer-key=82ookirnTwWNXXqFwdOQMVZIamt8s1uT'

# Success Response Reference

  • HTTP Status Code: 200
  • Content Type: application/json
Parameter Type Description
account string Account Identifier
date_from string Default value: the date when the account is created. Contains the full date, hours, minutes, seconds, decimal part of seconds (for example, 2021-01-22T23:00:30)
date_to string Default value: today's date (for example, 2022-02-22T09:00:30)
items array An array containing information about invoices
pagination array Pagination info

Element items:

Parameter Type Description
invoice string Invoice Identifier
created string Invoice creation date (for example, 2022-02-22T09:00:30).
currency string Currency type
amount integer The amount specified when creating the invoice.
status string Invoice status. More information about status see here

Element pagination:

Parameter Type Description
total integer Total number of items
offset integer The sequence number of the element from which the counting starts.
Default value: 0
limit integer Number of items displayed that request will return.
Default value: 10

# Response example


	{
    "account": "apr-e729d9982f079fa86b10a0e3aa6ff37b",
    "date_from": "2021-10-22T08:58:14.253612",
    "date_to": "2021-12-21T07:16:07.847586",
    "items": [
        {
            "invoice": "06xm4jZXj2QOCl7a",
            "created": "2021-12-14T19:22:37.697770",
            "currency": "btc",
            "amount": 20000,
            "status": "created"
        },
        {
            "invoice": "1qR3v7JPQnSxM784",
            "created": "2021-11-26T14:27:13.858791",
            "currency": "btc",
            "amount": 30000,
            "status": "paid"
        },
        {
            "invoice": "3CgVS1uERs9oF2aa",
            "created": "2021-12-15T09:44:51.687270",
            "currency": "btc",
            "amount": 10000,
            "status": "expired"
        }
    ],
    "pagination": 
    {
        "limit": 10,
        "offset": 0,
        "total": 3
    }
	}

# Error response

  • HTTP Status Code: 400 500
  • Content Type: application/json

Playground