Creating an invoice

The Invoice object plays a central role in managing an order. The simplest Invoice contains an identifying name, along with the amount the customer will be charged and the currency unit for payment. However, the Invoice object has many other data fields to store all kinds of information about an order. For example, it can contain details about:

• Each item in the order (name, type, brand, quantity, cost…),
• Shipping (address, delivery method, expected date…)
• Sales tax (amount and rate)

…and many other things. See the API reference for full details.

When to create an Invoice

You need to provide the payment amount when creating an Invoice object, so the order must be finalized at the time (although refunds and other changes may happen in the future). You must also supply a name, so you should ensure that a suitable one is available before creating the invoice.

In a typical case, the customer might click the Checkout cart button (or otherwise begin the payment process), and then your client-side code sends an HTTP GET or POST request to your server. This request activates the appropriate handler in your server code to create the invoice with the required details.

The handler should send the ID of the Invoice back to your client-side code (web, iOS or Android) as part of the response. For example, with a web payment, you might include the ID string as a hidden field in the web form that submits the card details.

API calls

The following code shows how to create an invoice. The code also adds an optional InvoiceDevice object with the call to ProcessOut.newInvoiceDevice(). This identifies the payment channel that the customer is using (web, iOS or Android), which may be useful when you are working with native 3DS2 libraries. Note that you should specify the amount in the major unit of the currency rather than the minor unit (so this would mean dollars rather than cents if the currency is USD, for example).

See the page about setting up the APIs to learn how to install and import the ProcessOut libraries and how to create the client object used in the sample:

curl -X POST https://api.processout.com/invoices \
    -u test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x:key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB \
    -d name="Amazing invoice" \
    -d amount="4.99" \
    -d currency=USD

client.newInvoice().create({
    name:     "Amazing invoice",
    amount:   "4.99",
    currency: "USD",
    device:   client.newInvoiceDevice({
        channel: "web" // optional; can be web, ios or android
    })
}).then(function(invoice) {
    // invoice is our newly created resource

}, function(err) {
    // An error occured

});

invoice = client.new_invoice().create({
    "name":     "Amazing invoice",
    "amount":   "4.99",
    "currency": "USD",
    "device":   client.new_invoice_device({
        "device": "web" # optional; can be web, ios or android
    })
})

invoice = client.invoice.create(
    name:     "Amazing invoice",
    amount:   "4.99",
    currency: "USD",
    device:   client.invoice_device.new(
        channel: "web" # optional; can be web, ios or android
    )
)

$invoice = $client->newInvoice()->create(array(
    "name"     => "Amazing invoice",
    "amount"   => "4.99",
    "currency" => "USD",
    "device"   => $client->newInvoiceDevice(array(
        "channel" => "web" // optional; can be web, ios or android
    ))
));

iv, err := client.NewInvoice().Create(processout.InvoiceCreateParameters{
    Invoice: &processout.Invoice{
        Name:     processout.String("Amazing invoice"),
        Amount:   processout.String("4.99"),
        Currency: processout.String("USD"),
        InvoiceDevice: client.NewInvoiceDevice(processout.InvoiceDevice{
            // optional; can be web, ios or android
            Channel: processout.String("web"),
        }),
    },
})

At a minimum, you must supply a name, amount and currency in the options when you create an invoice, but you can also set many other fields of the Invoice object in the same way. Some of the fields are purely for storing your information but others are required for particular purposes that we describe elsewhere in the guide (for example, you must supply a return_url field to make an invoice compatible with Alternative Payment Methods).

Next steps

Once you have created the invoice, you can use its ID to authorize payment from a payment source.