Invoices

This feature provides an opportunity to create an invoice for a B2B or B2C client for a specified amount.

Invoice general flow

You should send a request with a particular set of fields to create an invoice.The response will contain an URL that you have to forward to the user for payment.

Your user will see an invoice name, amount and currency, and also specific parameters (depending on invoice type): timer, possibility to choose payment currency or estimated amount and currency of payment.

If you send an user email in request, this field will be filled out for the user. Otherwise, the user has to fill out this field themselves. After confirming currency and putting email, the user has to pay an invoice using a specified address before the expiry of the timer. This address is generated by CoinsPaid.

The invoice type will be externalized depending on the sent parameters. There are 3 types of invoice:

  1. Invoice without restriction of payment time. The user chooses a currency of payment themselves without time restriction. Rate will be fixed when the user confirms payment currency.

  2. Invoice with time restriction. The user chooses a currency of payment themselves, but the time restriction will be 15 minutes starting from invoice creation.

  3. Invoice with time restriction and without a possibility to choose payment currency. The user sees the amount and payment currency that they need to pay.

If the user fails to pay the invoice in due time the system will display failed status.

You will receive a callback about the successful transaction creation after it appears in the mempool. We will change the timer from 15 minutes to 24 hours. During this period of time the transaction will change its status to confirmed.

After the successful confirmation of the transaction, funds will be exchanged in a receiver currency and transferred to your account. The Merchant is charged a Fee for Operation after the Funds are credited to the account.

If the user sends an amount of funds that is more or less than specified one we will send a payback guideline to their email.

API Endpoint

post
Create Invoice

https://app.coinspaid.com/api/v2/invoices/create
Create invoice for the client for a specified amount.
Request
Response
Request
Body Parameters
timer
required
boolean
Time on the rate is fixed for invoice payment (15 minutes). During this time the user has to pay an invoice.
name
required
string
Invoice name that will be displayed to the user
description
optional
string
Invoice description that will be displayed to the user
currency
required
string
ISO invoice currency that you want to receive from the user, for example: “EUR”
sender_currency
optional
string
Currency of user invoice payment (3rd type invoice will be externalized at the time of sending this parameter with timer= true), example: “BTC“
amount
required
integer
Invoice amount that you want to receive from the user, example: “106.75“
foreign_id
required
string
Unique foreign ID in your system, example: "164"
url_success
required
string
URL on which we redirect the user in case of a successful invoice payment, example: “https://merchant.name.com/url_success“
url_failed
required
string
URL on which we redirect the user in case of an unsuccessful invoice payment, example: “https://merchant.name.com/url_failed“
email_user
optional
string
In case the payment amount does not match the amount stated above, we will send an email to the stated address with instructions on funds recovery. In case of underpayment, the whole amount will be refunded. In case of overpayment, user will be able to recover the difference by following the instructions.
Response
200: OK
Example of success response
{
"data":{
"id":79,
"url":"https://app.coinspaid.com/invoice/RB9NZv",
"foreign_id":164,
"name":"TEST NAME",
"status":"created",
"currency":"EUR",
"amount":"106.75",
"sender_currency":"BTC",
"sender_amount":null,
"fixed_at":1581929889,
"release_at":1581930789
}
}
400: Bad Request
Example of response with errors
{
"errors":{
"foreign_id":"The foreign id has already been taken."
}
}

Invoice Type

1st Type

Invoice without restriction of payment time

This invoice type allows the user to choose the payment currency themselves without a time restriction. The rate will be fixed when the user confirms the payment currency.

By following the link the user will see the information about the invoice and also will be able to choose the payment currency.

Request example:
"timer": false,
"name": "Invoice Title",
"currency": "EUR",
"amount": 106.75,
"foreign_id": 196,
"url_success": "http://success.test",
"url_failed": "http://failed.test",
Response example:
{
"data":{
"id":127,
"url":"https://wallet.coinspaid.com/invoice/iEU3uh",
"foreign_id":205,
"address":null,
"name":"Invoice Title",
"status":"created",
"currency":"EUR",
"amount":"106.75000000",
"sender_currency":null,
"sender_amount":null,
"fixed_at":null,
"release_at":null
}
}

After confirming the currency and putting email, the rate will be fixed for 15 minutes. During this period of time the user has to pay the invoice using the specified address.

2nd Type

Invoice with time restriction

This invoice type allows the user to choose the payment currency themselves, but the time restriction will be 15 minutes starting from the invoice creation.

By following the link the user will see the information about the invoice, timer and will also be able to choose the payment currency. The rate will be fixed after the invoice creation.

Request example:
"timer": true,
"name": "Invoice Title",
"currency": "EUR",
"amount": 106.75,
"foreign_id": 196,
"url_success": "http://success.test",
"url_failed": "http://failed.test",
Response example:
{
"data":{
"id":130,
"url":"https://wallet.coinspaid.com/invoice/XJrbOG",
"foreign_id":208,
"address":null,
"name":"Invoice Title",
"status":"created",
"currency":"EUR",
"amount":"106.75000000",
"sender_currency":null,
"sender_amount":null,
"fixed_at":1582815161,
"release_at":1582816061
}
}

After confirming the currency and inputting the email, the user has to pay the invoice using the specified address before the expiry of the timer.

3rd Type

Invoice with time restriction and without the possibility to choose payment currency

This invoice type allows the user to pay the invoice themselves in a definite currency with a time restriction for 15 minutes starting from invoice creation.

By following the link the user will see the information about the invoice, 15 minutes timer and the payment currency. The rate will be fixed after the invoice creation.

Request example:
"timer": true,
"name": "Invoice Title",
"currency": "EUR",
"sender_currency": "BTC",
"amount": 106.75,
"foreign_id": 196,
"url_success": "http://success.test",
"url_failed": "http://failed.test",
Response example:
{
"data":{
"id":131,
"url":"https://wallet.coinspaid.com/invoice/8ppbsV",
"foreign_id":209,
"address":"91TESTBTCADDRESS",
"name":"Invoice Title",
"status":"created",
"currency":"EUR",
"amount":"106.75000000",
"sender_currency":"BTC",
"sender_amount":"0.01060080",
"fixed_at":1582815352,
"release_at":1582816252
}
}

After inputting the email, the user has to pay the invoice using the specified address before the expiry of the timer.

Invoice failed

Invoice fails upon the occurrence of any of the following:

  1. 15 minutes timer expiration.

  2. Transaction has processing status for more than 24 hours.

  3. The user paid an amount less than was requested. In this case the transaction will have a confirmed status but invoice will have a failed status.

Invoice callbacks

If the invoice payment is paid by installments, you will receive a callback for each part.

{
"id":2688875,
"type":"deposit_exchange",
"crypto_address":{
"id":384710,
"currency":"BTC",
"convert_to":"EUR",
"address":"0x4b41a526d3d12de36bdf969e7b70fd0bd2e0d265",
"tag":null,
"foreign_id":"9AW1KI7LesB9yxWcT2T"
},
"currency_sent":{
"currency":"EUR",
"amount":"500"
},
"currency_received":{
"currency":"BTC",
"amount":"0.05075",
"amount_minus_fee":"0.057"
},
"transactions":[
{
"id":717557,
"currency":"BTC",
"transaction_type":"blockchain",
"type":"deposit",
"address":"0x4b41a526d3d12de36bdf969e7b70fd0bd2e0d265",
"tag":null,
"amount":"0.0406",
"txid":"0x19f9094e12dfc6cb14910d6057269d10f39dfdc7c8b0d0e22b789c3e5d03b9e7",
"confirmations":"2"
}
],
"fees":[
{
"type":"fee_crypto_deposit_to_fiat",
"currency":"BTC",
"amount":"0.00075"
}
],
"invoice":{
"id":168,
"foreign_id":11,
"status":"pending",
"currency":"EUR",
"sender_currency":"BTC",
"amount":"500",
"amount_to_pay":"100"
},
"error":"",
"status":"processing"
}

You will receive a callback about the successful transaction creation after it appears in the mempool. We will change the timer from 15 minutes to 24 hours. During this period of time the transaction will change its status to confirmed.

{
"id":2688874,
"type":"deposit_exchange",
"crypto_address":{
"id":384709,
"currency":"BTC",
"convert_to":"EUR",
"address":"0x4b41a526d3d12de36bdf969e7b70fd0bd2e0d264",
"tag":null,
"foreign_id":"8FW1KI7LesB9yxWcK1K"
},
"currency_sent":{
"currency":"EUR",
"amount":"500"
},
"currency_received":{
"currency":"BTC",
"amount":"0.05075",
"amount_minus_fee":"0.05"
},
"transactions":[
{
"id":717556,
"currency":"BTC",
"transaction_type":"blockchain",
"type":"deposit",
"address":"0x4b41a526d3d12de36bdf969e7b70fd0bd2e0d264",
"tag":null,
"amount":"0.05075",
"txid":"0x19f9094e12dfc6cb14910d6057269d10f39dfdc7c8b0d0e22b789c3e5d03b9e6",
"confirmations":"1"
}
],
"fees":[
{
"type":"fee_crypto_deposit_to_fiat",
"currency":"BTC",
"amount":"0.00075"
}
],
"invoice":{
"id":167,
"foreign_id":11,
"status":"pending",
"currency":"EUR",
"sender_currency":"BTC",
"amount":"500",
"amount_to_pay":"0"
},
"error":"",
"status":"processing"
}

In case of a successful invoice payment you will receive the following callback:

{
"id":2688874,
"type":"deposit_exchange",
"crypto_address":{
"id":384709,
"currency":"BTC",
"convert_to":"EUR",
"address":"0x4b41a526d3d12de36bdf969e7b70fd0bd2e0d264",
"tag":null,
"foreign_id":"8FW1KI7LesB9yxWcK1K"
},
"currency_sent":{
"currency":"EUR",
"amount":"500"
},
"currency_received":{
"currency":"BTC",
"amount":"0.05075",
"amount_minus_fee":"0.05"
},
"transactions":[
{
"id":717556,
"currency":"BTC",
"transaction_type":"blockchain",
"type":"deposit",
"address":"0x4b41a526d3d12de36bdf969e7b70fd0bd2e0d264",
"tag":null,
"amount":"0.05075",
"txid":"0x19f9094e12dfc6cb14910d6057269d10f39dfdc7c8b0d0e22b789c3e5d03b9e6",
"confirmations":"1"
}
],
"fees":[
{
"type":"fee_crypto_deposit_to_fiat",
"currency":"BTC",
"amount":"0.00075"
}
],
"invoice":{
"id":167,
"foreign_id":11,
"status":"confirmed",
"currency":"EUR",
"sender_currency":"BTC",
"amount":"500",
"amount_to_pay":"0"
},
"error":"",
"status":"confirmed"
}

In case of an unsuccessful invoice payment you will receive the following callback:

15 minutes timer expired:

{
"id":167,
"foreign_id":11,
"status":"failed",
"reason":"not_paid",
"currency":"EUR",
"sender_currency":"BTC",
"amount":"500",
"amount_to_pay":"0",
"transactions":[
{
"id":717556,
"currency":"BTC",
"transaction_type":"blockchain",
"type":"deposit_exchange",
"address":"0x4b41a526d3d12de36bdf969e7b70fd0bd2e0d264",
"tag":null,
"amount":"0.05075",
"txid":"0x19f9094e12dfc6cb14910d6057269d10f39dfdc7c8b0d0e22b789c3e5d03b9e6",
"confirmations":"1"
}
],
"fees":[
{
"type":"fee_crypto_deposit_to_fiat",
"currency":"BTC",
"amount":"0.00075"
}
],
"fixed_at":1582620928,
"release_at":1582621828
}

Transaction has processing status for more than 24 hours:

{
"id":167,
"foreign_id":11,
"status":"failed",
"reason":"not_confirmed",
"currency":"EUR",
"sender_currency":"BTC",
"amount":"500",
"amount_to_pay":"500",
"transactions":[
{
"id":717556,
"currency":"BTC",
"transaction_type":"blockchain",
"type":"deposit_exchange",
"address":"0x4b41a526d3d12de36bdf969e7b70fd0bd2e0d264",
"tag":null,
"amount":"0.05075",
"txid":"0x19f9094e12dfc6cb14910d6057269d10f39dfdc7c8b0d0e22b789c3e5d03b9e6",
"confirmations":"1"
}
],
"fees":[
{
"type":"fee_crypto_deposit_to_fiat",
"currency":"BTC",
"amount":"0.00075"
}
],
"fixed_at":1582620928,
"release_at":1582621828
}

The user paid an amount less than was requested. In this case the transaction will have a confirmed status but the invoice will have a failed status:

{
"id":167,
"foreign_id":11,
"status":"failed",
"reason":"not_fully_paid",
"currency":"EUR",
"sender_currency":"BTC",
"amount":"500",
"amount_to_pay":"100",
"transactions":[
{
"id":717556,
"currency":"BTC",
"transaction_type":"blockchain",
"type":"deposit_exchange",
"status":"confirmed",
"address":"0x4b41a526d3d12de36bdf969e7b70fd0bd2e0d264",
"tag":null,
"amount":"0.0406",
"txid":"0x19f9094e12dfc6cb14910d6057269d10f39dfdc7c8b0d0e22b789c3e5d03b9e6",
"confirmations":"13"
}
],
"fees":[
{
"type":"fee_crypto_deposit_to_fiat",
"currency":"BTC",
"amount":"0.0006"
}
],
"fixed_at":1582620928,
"release_at":1582621828
}