Link Admin API Guide

Link is a fully integrated express payment method via Stripe, supported both in the storefront checkout and via the Admin API.

Link transactions send the customer through a Link redirect flow, with the resulting order information provided back to your application. Below are the steps needed to get Link set up and working on the Admin API.

API Payment Redirect Flow

Below is a high-level overview of the user flow when creating orders on the Admin API that utilize the payment method redirect flow.

Create Order on Admin API

When creating a new order using Link using the orders_create API method, you must specify the payment_method=link as well as provide a payment_return_url. The payment_return_url is your endpoint that will receive a POST request containing the final order data.

Payment Details for Order with Link

{
    "payment_method": "link",
    "payment_details": {
        "payment_return_url": "<external checkout url>",
        "payment_gateway": "<gateway id>", // optional
        "payment_gateway_group": "<gateway group id>" // optional
    }
}

You can optionally provide a payment_gateway when creating the order to use a Link account connected to a specific gateway.

Redirect Customer to Link

The response when creating the order will provide a payment_complete_url. Your application should redirect the customer to this URL for completing the payment on Link.

Response with Payment Complete URL

{
    "reference_transaction_id": null,
    "payment_complete_url": "<unique checkout url>"
}

Receiving Order Data

After the customer has completed their payment, they will be redirected to your application with a POST request containing data in the response key comprising all of the order information as a string. See examples below.

Order data structure follows Admin Order API and is application/x-www-form-urlencoded in a variable called response. If the order data is an empty dictionary , it means payment collection was unsuccessful and the order was not created.

Example Parsing of Order Data

import json

def order_receiver_view(request):
    data = json.loads(request.POST.get("response"))
    ...
    return HttpResponse(status=201)

Upsells

Link supports one-click upsells through the ordersAddLineItemsCreate API, enabling additional items to be added to the order with a payment transaction.

Recurring

Link via Stripe supports recurring transactions and can be used as a payment method for an order with subscription items.