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"
}

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
    }
  ],
  "checkoutSetup": {
    "selectedPaymentMethod": {
      "type": "Invoice"
    },
    "recurringPayments": "Hidden",
    "emailInvoice": "Hidden",
    "language": "English",
    "mode": "B2C",
    "callbackUrl": "string",
    "displayItems": true,
    "smsNewsletterSubscription": "Hidden",
    "emailNewsletterSubscription": "Hidden",
    "differentDeliveryAddress": "Hidden",
    "termsAndConditionsUrl": "string",
    "itegrityConditionsUrl": "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"
    },
    "userIputs": {
      "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"
    },
    "userIputs": {
      "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
B2BB2BInfo Business to business checkout setup
ExtraIdentifiersExtraIdentifiersPartner’s checkout session identifiers

Item

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

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
ItegrityConditionsUrlstringCustom integrity link. This setup replace set T&C link from Partner onboarding application

B2C Info

PropertyData typeDescription
CustomerTokenstringCustomer’s token
InvoicingAddressAddressCustomerCustomer’s invoicing address
DeliveryAddressDeliveryAddress Customer’s delivery address
UserIputsUserIputsAmount

B2B Info

PropertyData typeDescription
InvoicingAddressAddressCompanyObject
DeliveryAddressDeliveryAddressDescription of the item
UserIputsB2BUserInputsAdditional notes

Delivery Address

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

B2C User Iputs

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 Iputs

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 n 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 value Reference name

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
    )),
);

$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"
}