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:

1. Create a customer profile by creating a customer object.
2. Post an invoice including invoicelines by creating an invoice object.
3. Register the preferred payment method of choice, by implementing a Payment provider.
4. 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.

1. 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

2. Once the invoice is booked, the invoice can be marked as paid, may be credited or cancelled.
3. 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.

1. First step of the payment flow is to understand if the Customer of the Invoice holds a default payment method.
2. If so, the payment flow immediate upon booking the invoice, will issue a payment of the invoice using the payment method of the customer.
3. If the payment is completed succesfully the Invoice will be marked a paid setting the PaymentDate and PaymentStatus, and a resulting Transaction of completed.
4. If the payment fails, the Invoice is not marked as paid, any matching Dunning Flows are triggered and a failed Transaction 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 required Payment methods. The customer customer record must be created before posting the invoice. Record the CustomerID 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.