E-commerce & Webshop
As an e-commerce and webshop, handling a shopcart purchase and checkout flow is all about the touchpoints of a customer. Upodi is a subscription platform, a billing platform and a payment aggregation platform in one. We center around the customer by providing the ability to process e-commerce transactions using custom invoicing.
Centering on the customer also enables mixed basket options by including subscription sign-up into the shopping flow.
Our comprehensive billing engine, Upodi Billing support processing customized invoices typically from a webshop, one-off payment or customers whom want to leverage the integration of payment and billing infrastructure across multiple payment providers.
Amazon.com educated the modern consumer
In the late 90's, Amazon.com introduced one-click checkout, enabling a simple yet supportive checkout for repeat purchases. By creating a central customer profile, with payment method of choice, Amazon.com could reduce abandon carts and process new transactions much faster.
- The requirements is a central customer profile.
This guide help understand how a developer will integrate with Upodi Billing using our API. This guide is intended for developers
.
Understanding the shop flow
As the last step of the checkout flow, an e-commerce webshop must post all items of the shopping cart as an invoice onto a customer profile. Steps for the shop flow includes:
- Create a customer profile by creating a customer object.
- Post an invoice including invoicelines by creating an invoice object.
- Register the preferred payment method of choice, by implementing a Payment provider.
- Book and complete the checkout to start processing the payment.
Understanding the invoice flow
Posted Invoices are generated as draft
using the API. Invoices in stage of draft
can be deleted, edited and booked. Once initially posted the invoice flow is a follows.
- The
draft
invoices await to be booked. Booking an invoice will basically mark the invoice as unchangeable and must be credited once booked.
curl -X PUT "https://api.upodi.io/v3/invoices/1faa6aaf-8327-46a7-ae16-783e4dade095/book"
-H "Content-Type: application/json"
-H "Authorization: Bearer Zjc0YjNj....NGRk;"
PUT https://api.upodi.io/v3/invoices/1faa6aaf-8327-46a7-ae16-783e4dade095/book HTTP/1.1
- Once the invoice is booked, the invoice can be marked as
paid
, may becredited
orcancelled
. - A booked invoice is not
paid
initially, however once the invoice is booked, Upodi Billing will initiate the payment flow as described next.
Understanding the payment flow
Booked invoices will be reviewed by the Upodi Billing engine. A payment flow is triggered once the invoice is booked as described.
- First step of the payment flow is to understand if the
Customer
of theInvoice
holds a default payment method. - If so, the payment flow immediate upon booking the invoice, will issue a payment of the invoice using the payment method of the customer.
- If the payment is completed succesfully the
Invoice
will be marked a paid setting the PaymentDate and PaymentStatus, and a resultingTransaction
of completed. - If the payment fails, the
Invoice
is not marked as paid, any matching Dunning Flows are triggered and a failedTransaction
is recorded.
Posting an invoice
Invoices are posted using the API. An invoice posted to Upodi Billing, will need to include all details including invoice lines, reference to customer and payment terms.
Before posting the invoice, please create both the
Customer
and/or any requiredPayment methods
. The customer customer record must be created before posting the invoice. Record theCustomerID
and post the invoice (using 6051cd7b-dcd2-4ced-8c6a-f19d5515bafc in this example).
curl -X POST "https://api.upodi.io/v3/invoices"
-H "Content-Type: application/json"
-H "Authorization: Bearer Zjc0YjNj....NGRk;"
'{' \
' "CustomerID": "6051cd7b-dcd2-4ced-8c6a-f19d5515bafc",' \
' "CurrencyCode": "DKK",' \
' "Description": "Description on my invoice",' \
' "InvoiceLines": [' \
' {' \
' "Title": "Title",' \
' "Description": "Describe this",' \
' "Quantity": 8,' \
' "UnitPrice": 50,' \
' "Sku": "flatFee",' \
' "Discount": "0.15",' \
' "PeriodStart":"2018-12-20T13:22:00+01:00",' \
' "PeriodEnd":"2018-12-23T01:20:00+01:00",' \
' },' \
' {' \
' "Description": "Empty stuff",' \
' "Quantity": 2,' \
' "UnitPrice": 2.99,' \
' "Sku": "flatFee",' \
' }' \
' ]' \
'}'
POST https://api.upodi.io/v2/invoices HTTP/1.1
{
"CustomerID": "6051cd7b-dcd2-4ced-8c6a-f19d5515bafc",
"CurrencyCode": "DKK",
"Description": "Mohahaha",
"DueDate":"2017-12-05T00:00:00+01:00",
"InvoiceLines": [
{
"Title": "Title",
"Description": "Describe this",
"Quantity": 8,
"UnitPrice": 50,
"Sku": "flatFee",
"Unit": "Balls",
"Discount": "0.15",
"PeriodStart":"2018-12-20T13:22:00+01:00",
"PeriodEnd":"2018-12-23T01:20:00+01:00",
"IsEmptyLine": false
},
{
"Description": "Empty stuff",
"Quantity": 2,
"UnitPrice": 2.99,
"Sku": "flatFee",
"IsEmptyLine": false
},
{
"Description": "Descriptive invoice line",
"Title": "Empty Line",
"IsEmptyLine": true
}
]
}
Booking the invoice
Once the invoice is ready to be booked, call the Book
method to initate the booking flow. The invoice will be stamped an invoice number, and payment terms apply to the invoice of subject. In addition, the payment flow is initated should the Customer
hold a default payment method.
curl -X PUT https://api.upodi.io/v3/Invoices/1faa6aaf-8327-46a7-ae16-783e4dade095/book
-H "Content-Type: application/json"
-H "Authorization: Bearer Zjc0YjNj....NGRk;"
PUT https://api.upodi.io/v3/Invoices/1faa6aaf-8327-46a7-ae16-783e4dade095/book HTTP/1.1
Dunning and payment retries
Upon booking and payment of an invoice, Upodi Billing will monitor the status of the invoice and payment. Should a payment decline for unknown reasons, the dunning process will be initated. Upodi Billing support advances dunning scenarious upon which fall back payments are issued with mutiple payment providers. Configuration of the Dunning Process is done in Upodi.
Use webhooks to capture the asynchronious feedback on the booking and payment flows Webhooks.
What's next
Custom invoicing is one of multiple options to use Upodi Billing. You can read more on how to use payment methods, recurring billing & subscription management on the broad documentation.
- Read more on our subscription Sign up flow.
- Please continue reading the full documentation - Introduction.
Updated over 2 years ago