Created with Sketch.
Created with Sketch.
Checkout 3.0

How to get 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.

API Authentication

Base URLs

Avarda base URLs for Checkout 3.0 Backend API:

Stage environment: https://avdonl-s-checkout.avarda.org

Production environment: https://avdonl-p-checkout.avarda.org

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
GET {api_url}/api/partner/tokens
Content-type: application/json

{
  "clientId": "659e57c9-d970-4db8-b003-8ba04cc157f9",
  "clientSecret": "4~{x*6%gvBt(:aD"
}

Payload:

PropertyData type
clientIdstring
clientSecretstring

Example

<?php
$api_url = "https://avdonl-s-checkout.avarda.org";
// 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": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InBpVmxsb1FEU01LeGgxbTJ5Z3FHU1ZkZ0ZwQSIsImtpZCI6InBpVmxsb1FEU01LeGgxbTJ5Z3FHU1ZkZ0ZwQSJ9.eyJhdWQiOiIwMDAwMDAwMi0w...",
    "tokenExpirationUtc": "2020-01-01T09:24:42.2011052Z"
}

Payload:

PropertyData typeDescription
tokenstringJWT token in string format – “Partner Access Token”
tokenExpirationUtcstringDateTime 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": {
    "selectedPaymentMethodType": "Invoice",
    "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

PropertyData typeDescription
Items[ Item ]List of item objects
CheckoutSetupCheckoutSetupSetup for checkout payment
B2CB2CInfoBusiness to customer checkout setup
B2BB2BInfoBusiness to business checkout setup
ExtraIdentifiersExtraIdentifiersPartner’s checkout session identifiers

Item

PropertyData typeDescription
DescriptionstringItem name
Notes string Item notes
AmountstringItem price
TaxCodestringTax code
TaxAmountstringTax amount
QuantitydecimalQuantity

Checkout Setup

PropertyData typeDescription
SelectedPaymentMethodTypePaymentMethodTypePreselected pamynet method
RecurringPaymentsCheckBoxStateTypeList of item objects . Can be set only when Checkout site definition have allowed Recurring payments
EmailInvoiceCheckBoxStateTypeSetup of recurring send invoice by email check-box. Can be set only when Checkout site definition have allowed Email invoice
LanguageLanguageIn which language to display the checkout form.
ModePurchaseModeB2C or B2B. Default is B2C
CompletedNotificationUrlstringCallback URL called after complete payment
DisplayItemsboolParameters that tells whether the item list should be displayed inside the checkout form. If true, checkout will contains view with purchase list of items.
SmsNewsletterSubscriptionCheckBoxStateTypeWhether to offer a SMS newsletter subscription and whether it should be selected by default.
EmailNewsletterSubscriptionCheckBoxStateTypeWhether to offer a Email newsletter subscription and whether it should be selected by default.
DifferentDeliveryAddressCheckBoxStateTypeDelivery address check-box setup. Checked can be only with valid delivery address
TermsAndConditionsUrlstringCustom T&C link. This setup replace set T&C link from Partner onboarding application
IntegrityConditionsUrlstringCustom integrity link. This setup replace set T&C link from Partner onboarding application
EnableB2BLinkboolEnable or disable b2b link visibility
EnableCountrySelectorboolEnable or disable country selector
ShowThankYouPageboolParameter to show or hide thank you page

B2C Info

PropertyData typeDescription
CustomerTokenstringCustomer’s token
InvoicingAddressAddressCustomerCustomer’s invoicing address
DeliveryAddressDeliveryAddressCustomer’s delivery address
UserInputsUserInputsUser inputs

B2B Info

PropertyData typeDescription
InvoicingAddressAddressCompanyCompany’s invoicing address
DeliveryAddressDeliveryAddressCompany’s delivery address
UserInputsB2BUserInputsUser inputs

Delivery Address

PropertyData typeDescription
Address1string 0-100 length
Address2string 0-100 length
Zipstring 5 length
City string 0-30 length
Country string Mandatory if Branch setup contains ShowCountryInCheckoutForm set on true
FirstName string 0-40 length
LastName string 0-40 length
TypeDeliveryAddressType Type of address (Private/Company)

B2C User Inputs

PropertyData typeDescription
Phone string Customer’s phone number passed by a partner’s application.
EmailstringCustomer’s e-mail address passed by a partner’s application.

B2B User Inputs

PropertyData typeDescription
Phone string Customer’s phone number passed by a partner’s application.
EmailstringCustomer’s e-mail address passed by a partner’s application.
Reference string Custom customer’s reference for payment identifying

Extra Identifiers

PropertyData typeDescription
OrderReference string Merchant custom ID reference
LoyaltyNumberstringCan be a number of a customer’s membership card.
ProductGroup string Defined the product category.
Attachment string Random merchant’s data (some kind of serialized JSON for example)
Description string An optional description provided by partner. May be multi-line and may contain whatever the partner want.
ReferenceName string Merchant custom value Reference name
PosId string Merchant custom PosId

Example

<?php
$api_url = "https://avdonl-s-checkout.avarda.org";
// "Partner access token" generated by calling `$api_url/api/partner/tokens` see more info: <https://docs.avarda.com/checkout-3/how-to-get-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"
}