This guide walks you through the complete flow: create credentials, authenticate, create a checkout session, and handle the payment result.
How it works
Every Dintero integration follows the same pattern:
Get credentials
Create an API client in Backoffice and save your Client ID and Client Secret. Authenticate
Exchange credentials for a bearer token.
Create a session
Send your order details to Dintero and get back a checkout URL.
Handle the result
Dintero calls your server with the transaction result. Capture, refund, or void as needed.
Prerequisites
Sandbox vs production
Every Dintero account has two environments, identified by the account ID prefix:
| Prefix | Environment | Example | Purpose |
|---|
T | Sandbox | T12345678 | No real money, use test cards |
P | Production | P12345678 | Live — real payments |
Start with your sandbox account (T prefix). Switch to production by creating new API credentials on your P account when you’re ready to go live.
Step 1: Create API credentials
Open Backoffice
Go to Settings > API clients (under API & Integrations).
Create a client
Click Create new API client > Checkout client, enter your website URL, and click Create.
Save credentials
Copy the Client ID and Client Secret immediately.
The Client Secret is shown only once. Store it securely — you cannot retrieve it later.
Step 2: Get an access token
Exchange your credentials for a bearer token using the OAuth 2.0 client credentials flow.
curl -X POST https://api.dintero.com/v1/accounts/T12345678/auth/token \
-u "CLIENT_ID:CLIENT_SECRET" \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"audience": "https://api.dintero.com/v1/accounts/T12345678"
}'
import requests
response = requests.post(
"https://api.dintero.com/v1/accounts/T12345678/auth/token",
auth=("CLIENT_ID", "CLIENT_SECRET"),
headers={"Content-Type": "application/json"},
json={
"grant_type": "client_credentials",
"audience": "https://api.dintero.com/v1/accounts/T12345678",
},
)
access_token = response.json()["access_token"]
const response = await fetch(
"https://api.dintero.com/v1/accounts/T12345678/auth/token",
{
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization:
"Basic " + Buffer.from("CLIENT_ID:CLIENT_SECRET").toString("base64"),
},
body: JSON.stringify({
grant_type: "client_credentials",
audience: "https://api.dintero.com/v1/accounts/T12345678",
}),
}
);
const { access_token } = await response.json();
{
"access_token": "eyJhbGci...t7P4",
"token_type": "Bearer",
"expires_in": 14400
}
Authorization: Bearer {access_token} header for all API calls.
Step 3: Create a checkout session
A session represents a customer’s order. Send the order details and get back a checkout URL.
curl -X POST https://checkout.dintero.com/v1/sessions-profile \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": {
"return_url": "https://example.com/thankyou",
"callback_url": "https://example.com/callback"
},
"order": {
"amount": 29990,
"currency": "NOK",
"merchant_reference": "order-001",
"items": [
{
"id": "item-1",
"line_id": "1",
"description": "Blue T-Shirt",
"quantity": 1,
"amount": 29990,
"vat_amount": 5998,
"vat": 25
}
]
},
"profile_id": "default"
}'
response = requests.post(
"https://checkout.dintero.com/v1/sessions-profile",
headers={"Authorization": "Bearer ACCESS_TOKEN"},
json={
"url": {
"return_url": "https://example.com/thankyou",
"callback_url": "https://example.com/callback",
},
"order": {
"amount": 29990, # 299.90 NOK
"currency": "NOK",
"merchant_reference": "order-001",
"items": [
{
"id": "item-1",
"line_id": "1",
"description": "Blue T-Shirt",
"quantity": 1,
"amount": 29990,
"vat_amount": 5998,
"vat": 25,
}
],
},
"profile_id": "default",
},
)
session = response.json()
const response = await fetch(
"https://checkout.dintero.com/v1/sessions-profile",
{
method: "POST",
headers: {
Authorization: "Bearer ACCESS_TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: {
return_url: "https://example.com/thankyou",
callback_url: "https://example.com/callback",
},
order: {
amount: 29990, // 299.90 NOK
currency: "NOK",
merchant_reference: "order-001",
items: [
{
id: "item-1",
line_id: "1",
description: "Blue T-Shirt",
quantity: 1,
amount: 29990,
vat_amount: 5998,
vat: 25,
},
],
},
profile_id: "default",
}),
}
);
const session = await response.json();
Amounts are in the smallest currency unit. 299.90 NOK = 29990.
{
"id": "T12345678.xxxxxxxxxxxxxxxxxxxx",
"url": "https://checkout.dintero.com/v1/view/T12345678.xxxxxxxxxxxxxxxxxxxx"
}
Step 4: Display the checkout
Show the checkout to your customer using the Web SDK. Install it with npm:
npm install @dintero/checkout-web-sdk
Not sure which approach to use?Redirect sends the customer to a Dintero-hosted page — minimal setup, no iframe. Embed renders the checkout inside your page — more control over the experience.See the SDK documentation for a full comparison. Send the customer to the Dintero-hosted payment page:import { redirect } from "@dintero/checkout-web-sdk";
redirect({
sid: "T12345678.xxxxxxxxxxxxxxxxxxxx",
});
url from step 3. Embed the checkout in your page:<div id="checkout-container"></div>
import { embed } from "@dintero/checkout-web-sdk";
await embed({
container: document.getElementById("checkout-container"),
sid: "T12345678.xxxxxxxxxxxxxxxxxxxx",
});
Step 5: Handle the result
After payment, Dintero notifies you through two channels:
| Channel | How | Reliable? | Use for |
|---|
| callback_url | GET to your server | Yes (retried up to 20 times) | Verify payment, fulfill order |
| return_url | Customer redirect | No (browser may close) | Show confirmation page |
Always verify the transaction via the callback. The redirect is not guaranteed.
What’s next
Express Checkout
Skip address forms for faster conversions.
Embed vs redirect
Compare integration approaches.
Test data
Test cards and sandbox scenarios.
