Using Orders and Checkout together

Introduction

The order management service and checkout service are built to be used together, but can also be used entirely separate.

This flexibility can make it hard to understand exactly how to use them together, so we'll go through that in detail here.

We will go through these steps:

• Creating a draft order
• Completing the draft order
• Creating a checkout session to pay this order
• Retrieving the paid transaction
• Mark the order as authorized after the transactions is paid
• Capturing the transaction
• Marking the order as captured
• Refunding the transaction
• Marking the order as refunded

Authorization

To access the API, you need to create an API Client with the scopes:

• admin:checkout
• admin:shopping

Note down the client_id and client_secret, and use them throughout these examples.

Create order

• POST /v1/accounts/{aid}/shopping/draft_orders
• PUT /v1/accounts/{aid}/shopping/draft_orders/{id}/complete

{
    "options": {
        "generate_order_id": "ALPHANUMERIC_9"
    },
    "order": {
        "currency": "NOK",
        "items": [
            {
                "id": "175938",
                "line_id": 1,
                "quantity": 2,
                "gross_amount": 39800,
                "tax_lines": [
                    {
                        "amount": 7960,
                        "percentage": 25
                    }
                ],
                "description": "Stablestol for utendørsbruk",
                "description_alias": "Stablestol"
            }
        ]
    }
}

After creating the draft_order and marking it as completed, it's time to create the session.

See Checkout for a detailed guide to the checkout.

Create session

• POST /v1/sessions-profile

When creating the session, use the order_id as merchant_reference.

The payload to create the session will look a bit like this:

{
    "url": {
        "return_url": "https://example.com/accept",
        "callback_url": "https://example.com/callback"
    },
    "order": {
        "amount": 39800,
        "currency": "NOK",
        "merchant_reference": "order_id",
        "items": [
            {
                "id": "175938",
                "line_id": "1",
                "description": "Stablestol for utendørsbruk",
                "quantity": 2,
                "amount": 39800,
                "vat_amount": 7960,
                "vat": 25
            }
        ]
    },
    "profile_id": "default_profile"
}

NB: profile_id might vary, see Backoffice to find the correct one.

# Get access token
curl 'https://api.dintero.com/v1/accounts/P11223351/auth/token' \
-H'Content-Type: application/json' \
--user client_id:client_secret -d'{
    "audience": "https://api.dintero.com/v1/accounts/P11223351",
    "grant_type": "client_credentials"
}'


// Create session
curl 'https://checkout.dintero.com/v1/sessions-profile' \
-H'Content-Type: application/json' \
-H'Authorization: Bearer token' -d 'json-body-from-above'

from dintero import Dintero

account_id = 'T12345678'
client_id = 'client_id'
client_secret = 'client_secret'

dintero = Dintero(
    account_id,
    client_id,
    client_secret)
checkout = dintero.checkout()
session_info = checkout.create_session(session_body)

When the session is created, see executing payment for the different methods of showing the session to the user.

When the payment is completed, you will receive a redirect or callback to your site with the session_id and its corresponding transaction. Poll the current status of the transaction to make sure that the status is AUTHORIZED.

Now that the payment is authorized, you should mark the funds as reserved on the order by creating an authorization:

Marking the order as authorized

• POST /v1/accounts/{aid}/shopping/orders/{order_id}/authorizations

{
    "items": [
        {
            "amount": 39800,
            "line_id": 1
        }
    ],
    "payment_details": {
        "payment_id": "transaction_id"
    },
    "success": true
}

Capturing the transaction

• POST /v1/transactions/{transaction_id}/capture

Once the items are ready to be shipped, you can capture the transaction. See capture transaction for details.

Marking the order as captured

You can now mark the order as captured.

• POST /v1/accounts/{aid}/shopping/orders/{order_id}/captures

{
    "items": [
        {
            "amount": 39800,
            "line_id": 1
        }
    ],
    "payment_details": {
        "payment_id": "transaction_id"
    },
    "success": true
}

Refunding the transaction

• POST /v1/transactions/{transaction_id}/refund

If the customer is not happy, you might want to refund the items. See refund transaction for details.

Mark order as refunded

• POST /v1/accounts/{aid}/shopping/orders/{order_id}/refund

You can now mark the order as refunded.

{
    "items": [
        {
            "amount": 39800,
            "line_id": 1
        }
    ],
    "payment_details": {
        "payment_id": "transaction_id"
    },
    "success": true
}