3DS2 Admin API Guide

3DS2 payments are fully supported via the Admin API to process the customer through an authentication flow, with the final transaction information and results provided back to your application.

info

Your store must have a 3DS2 enabled gateway to process 3DS2 transactions.

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 a 3DS2 enabled gateway, you’ll need to use the payment_method=bankcard 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 3DS2 Payment

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

tip

You can optionally provide a payment_gateway or payment_gateway_group when creating the order to use a specific payment gateway configured in the store.

Redirect to Payment Complete URL

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

Response with Payment Complete URL

{
    "reference_transaction_id": null,
    "payment_complete_url": "https://<domain>/payments/3ds-auth/?token=<transaction token>"
}

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

caution

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)