Creating an Invoice

Invoice::Create

An Invoice is the name (Class) given to a request for payment within GoCoin. As discussed here, 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
status string The status (state) of the invoice
payment_address string The address to pay the invoice in
crypto_balance_due decimal This is equal to , 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 / exchange rate based on GoCoin's Spot Price ie. 134 USD/BTC
spot_rate decimal / exchange rate based on GoCoin's Spot Price ie. 0.007 BTC/USD
usd_spot_rate decimal USD/ 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

Recent Discussions

19 Feb, 2017 11:23 PM
16 Feb, 2017 05:18 PM
16 Feb, 2017 12:34 PM
16 Feb, 2017 08:18 AM
16 Feb, 2017 06:51 AM