Invoice::Create


An Invoice is the name (Class) given to a request for payment within GoCoin. As discussed [here](http://help.gocoin.com/kb/setup-integration/what-can-i-do-with-gocoin), Invoices contain all information necessary for payment, unless they are of the special type 'Bill'


Creating an invoice requires an access token with the scope `'invoice_read_write'` or `'invoice_write'`


Request


```

Create a new invoice.

POST /merchants/:id/invoices

Headers:

 Accept: application/json


Body:

{

  "price_currency": "BTC",                                    

  "base_price": 134.00,                                        

  "base_price_currency": "USD",                                

  "callback_url": "https://www.example.com/gocoin/callback",

  "redirect_url": "https://www.example.com/redirect"

}

```


Response


```

Status Code: 201

Body:

{

    "id": "84c4fc04-66f2-49a5-a12a-36baf7f9f450",

    "status": "unpaid",

    "payment_address": "1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

    "price": "1.00000000",

    "crypto_balance_due": "1.00000000",

    "price_currency": "BTC",

    "valid_bill_payment_currencies": null,

    "base_price": "134.00",

    "base_price_currency": "USD",

    "service_fee_rate": "0.01",

    "usd_spot_rate": "1.0",

    "spot_rate": "0.00746268656716",

    "inverse_spot_rate": "134.0",

    "crypto_payout_split": "100",

    "confirmations_required": 2,

    "crypto_url": null,

    "gateway_url": "https://gateway.gocoin.com/invoices/84c4fc04-66f2-49a5-a12a-36baf7f9f450",

    "notification_level": null,

    "redirect_url": "http://www.example.com/redirect",

    "order_id": null,

    "refund_address": null,

    "item_name": null,

    "item_sku": null,

    "item_description": null,

    "physical": null,

    "customer_name": null,

    "customer_address_1": null,

    "customer_address_2": null,

    "customer_city": null,

    "customer_region": null,

    "customer_country": null,

    "customer_postal_code": null,

    "customer_email": null,

    "customer_phone": null,

    "user_defined_1": null,

    "user_defined_2": null,

    "user_defined_3": null,

    "user_defined_4": null,

    "user_defined_5": null,

    "user_defined_6": null,

    "user_defined_7": null,

    "user_defined_8": null,

    "data": null,

    "expires_at": "2014-01-02T22:08:09.599Z",

    "created_at": "2014-01-02T21:53:10.867Z",

    "updated_at": "2014-01-02T21:53:10.867Z",

    "server_time": "2014-01-02T23:59:12Z",

    "callback_url": "https://www.example.com/gocoin/callback",

    "merchant_id": "7af834d9-aa7a-423c-be16-33ea6a724007"

}


```


Parameters


The following parameters can be passed in the request body.


| Label | Type | Description | Default Value | Req. for: |

|------------|----|----|----------------|-----|

| base_price | decimal | The value of good or service being purchased. | | All |

| base_price_currency | string |The value of good or service being purchased | | All |

| price_currency | string | The currency the invoice is to be paid in | null | Invoice |

| type | string | Makes an invoice a bill (type: "bill") | null | Bill |

null | |

| redirect_url | string | Valid url where the customer will be sent after a payment through the hosted gateway | null |

| callback_url | string | Valid url where the webhook notifications will be sent after a payment through the hosted gateway | null |

| order_id | string | Identifier for tracking the order from your system  | null |

| refund_address | string | An address to return funds to the customer in the event of cancellation/refunding it | null |

| item_name | string | Label for the item being sold | null |

| item_sku | string | SKU for item for easier tracking | null |

| item_description | string | Optional description of item | null |

| customer_x | string | Optional customer information fields | null |

| user_defined_x | string | Optional pass through data fields - these are not displayed to the customer on the hosted gateway | null |

| data | string | Miscellaneous field | null |




The following parameters are returned in the invoice response, in addition to those that were passed in the request.


| Label | Type | Description |

|----|-----------|-------|

| id | uuid | A unique id for the invoice within GoCoin |

| price | decimal | A price to pay, calculated in <price_currency> |

| status | string | The status (state) of the invoice |

| payment_address | string | The address to pay the invoice in <price_currency> |

| crypto_balance_due | decimal | This is equal to <price>, unless the invoice was underpaid and a balance remains |

| crypto_url | string | Wallet friendly url - this can be used to generate payable QR Code. |

| gateway_url | string | URL to this invoice on the hosted gateway. Redirect your customer here, or use an iframe|

| created_at | string | ISO time of Invoice creation |

| updated_at | string | ISO time of Invoice's last update. This is relevant to Bill's only. |

| expires_at | string | ISO time set to 15 minutes from the time the invoice reaches 'unpaid' status (updated_at) |

| server_time | string | ISO time - reference of currency server time |

| merchant_id | uuid | Unique identifier for the issuing merchant |

| valid_bill_payment_currencies | array | An array of 3 letter currency codes for acceptable payment options. |

| inverse_spot_rate | decimal | <base_price_currency>/<price_currency> exchange rate based on GoCoin's Spot Price ie. 134 USD/BTC |

| spot_rate | decimal | <price_currency>/<base_price_currency> exchange rate based on GoCoin's Spot Price ie. 0.007 BTC/USD |

| usd_spot_rate | decimal | USD/<base_price_currency> exchange rate based on GoCoin's Spot Price |

| confirmations_required | integer | The number of confirmations before the invoice will be marked as 'ready_to_ship.' This is currently a fixed value and is not user editable. |

| service_fee_rate | decimal | Per transaction service fee. 0.01 = 1% |

| notification_level | string | unused, reserved |

| physical | string | unused, reserved