Getting Started

On this page, you will find information about how to authenticate with the Checkout 3.0 Backend API, construct the authentication header and how to Initialize payment.

Initialize payment API diagram

API Authentication

Base URLs

Avarda base URLs for Checkout 3.0 Backend API:

Stage environment: https://stage.checkout-api.avarda.com (opens in a new tab)

Production environment: https://checkout-api.avarda.com (opens in a new tab)

Obtain Partner access token

“Partner access token” is used as authentication for all further communication with the Checkout 3.0 Backend API. This token should never be displayed to the user or sent to the frontend of the application.

To obtain the token send POST request with clientId and clientSecret as a JSON to /api/partner/tokens.

# Obtain Partner access token
curl -X "POST ${api_url}/api/partner/tokens" \
	-H 'Content-type: application/json' \
    -H 'Accept: application/json' \
    -d  '{ "clientId": "659e57c9-d970-4db8-b003-8ba04cc157f9", "clientSecret": "4~{x*6%gvBt(:aD" }'

Payload:

Property	Data type
clientId	string
clientSecret	string

Example

<?php
$api_url = "https://stage.checkout-api.avarda.com";
// Use your CLIENT_ID and CLIENT_SECRET
$client_id = "659e57c9-d970-4db8-b003-8ba04cc157f9";
$client_secret = "4~{x*6%gvBt(:aD";
 
// Send POST request and save "Partner access token"
$request_url = "$api_url/api/partner/tokens";
$request_payload = array('clientId' => $client_id, 'clientSecret' => $client_secret);
 
$options = array(
    'http' => array(
        'header'  => "Content-type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($request_payload)
    )
);
 
$context = stream_context_create($options);
$result = file_get_contents($request_url, false, $context);
if ($result === false) { /* Handle error */
} else {
    $json_data = json_decode($result);
    $partner_access_token = $json_data->token;
    echo (string) $partner_access_token;
};

Return Value

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "tokenExpirationUtc": "2020-01-01T09:24:42.2011052Z"
}

Payload:

Property	Data type	Description
token	string	JWT token in string format – “Partner Access Token”
tokenExpirationUtc	string	DateTime in string format – easy access to expiration date of “Partner Access Token”. More information about handling of the token in Handling Partner access token

Initialize payment

Initialize payment and set up initial parameters such as: language; items list; etc. Please check the full list of options below.

Send a POST request with “Partner access token” as authorization with JSON data. Successful initialization returns a unique “Purchase JWT token” and “PurchaseId”. “Purchase JWT token” is used to display Checkout 3.0 form on the frontend of your application. “PurchaseId” is used in other Checkout 3.0 Backend API calls.

# Initialize a new payment
POST {api_url}/api/partner/payments
Content-type: application/json
Authorization: Bearer {partner_access_token}
 
{
"items": [
{
"description": "string",
"notes": "string",
"amount": 0,
"taxCode": "string",
"taxAmount": 0,
"quantity": 0
}
],
"checkoutSetup": {
"recurringPayments": "Hidden",
"emailInvoice": "Hidden",
"language": "English",
"mode": "B2C",
"completedNotificationUrl": "string",
"displayItems": true,
"smsNewsletterSubscription": "Hidden",
"emailNewsletterSubscription": "Hidden",
"differentDeliveryAddress": "Hidden",
"termsAndConditionsUrl": "string",
"integrityConditionsUrl": "string"
},
"b2C": {
"customerToken": "string",
"invoicingAddress": {
"address1": "string",
"address2": "string",
"zip": "string",
"city": "string",
"country": "AF",
"firstName": "string",
"lastName": "string"
},
"deliveryAddress": {
"address1": "string",
"address2": "string",
"zip": "string",
"city": "string",
"country": "AF",
"firstName": "string",
"lastName": "string",
"type": "Default"
},
"userInputs": {
"phone": "string",
"email": "string"
}
},
"b2B": {
"invoicingAddress": {
"address1": "string",
"address2": "string",
"zip": "string",
"city": "string",
"country": "AF",
"name": "string"
},
"deliveryAddress": {
"address1": "string",
"address2": "string",
"zip": "string",
"city": "string",
"country": "AF",
"firstName": "string",
"lastName": "string",
"type": "Default"
},
"userInputs": {
"phone": "string",
"email": "string",
"reference": "string"
}
},
"extraIdentifiers": {
"orderReference": "string",
"loyaltyNumber": "string",
"productGroup": "string",
"attachment": "string",
"description": "string",
"referenceName": "string",
"posId": "string"
}
}

Payload

Property	Data type	Description
Items	[ Item ]	List of item objects
CheckoutSetup	CheckoutSetup	Setup for checkout payment
B2C	B2CInfo	Business to customer checkout setup
B2B	B2BInfo	Business to business checkout setup
ExtraIdentifiers	ExtraIdentifiers	Partner’s checkout session identifiers

Example

<?php
$api_url = "https://stage.checkout-api.avarda.com";
// "Partner access token" generated by calling `$api_url/api/partner/tokens` see more info: <https://docs.avarda.com/checkout-3/getting-started/#obtain-partner-access-token>
$partner_access_token = "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IllNRUxIVDBnd...";
 
// Send POST request, save "Purchase JWT token" and "PurchaseId"
$request_url = "$api_url/api/partner/payments";
$request_payload = array(
    "checkoutSetup" => array(
        "language" => "English"
    ), "items" => array(array(
        "description" => "Test Item 1",
        "notes" => "Test Notes 1",
        "amount" => 50,
        "taxCode" => "20%",
        "taxAmount" => 10,
        "quantity" => 2
    )),
);
 
$options = array(
    'http' => array(
        'header'  => "Content-type: application/json\r\nAuthorization: Bearer $partner_access_token\r\n",
        'method'  => 'POST',
        'content' => json_encode($request_payload)
    )
);
$context = stream_context_create($options);
$init_result = file_get_contents($request_url, false, $context);
if ($init_result === false) { /* Handle error */
} else {
    $init_data = json_decode($init_result);
    $purchase_jwt_token = $init_data->jwt;
    $purchase_id = $init_data->purchaseId;
    echo (string) $purchase_id;
    echo (string) $purchase_jwt_token;
}

Return Value

{
  "purchaseId": "AVT3gn",
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJDaGVja291dCIsImp0aSI6IjljZGRhZWI4LWU1N2UtNGIwNC04ZDdjLTBjODc0YTA1MDY2MyIsIlB1cmNoYXNlSWQiOiJBVlQzZ24iLCJleHAiOjE1Nzg5MTE0OTh9.HMRidZgeOQtOQtXyHwanmfS0KwYXb73m5lkTeQ449co",
  "expiredUtc": "2020-01-01T09:02:03.2160375Z"
}

Overview Embed Checkout Form