CUSTOM INTEGRATION

Even if you don't use a supported e-Commerce platform, you can still fully integrate with Prism by creating several integration webhooks that you can link with your backend system. Prism provides the capability via webhook so you have the flexibility to implement the ones you need and handle it as you please. All Prism needs to know is how should we display it to the user.

The custom integration is commony done in 3 main parts:

  1. Product Integration
  2. Shipping Integration
  3. Checkout Integration

You don't have to implement all three but if you would like the deep integration to be fully functional, we advise you todo so.

This part of documentation will explain the overview and the 3 parts mentioned above.

Product Integration

In product integration, Prism will act as a proxy that will translate your product data structure into a standardized format that will be displayed to the user through all the available channels. The product used in this proxy integration will also be the one being used in the checkout integration.

Prism will act only as a proxy for all Product-related operations done in the Prism Dashboard. These operations include:

  1. Search product.
  2. Filter product.
  3. Gets product detail (such as price, stock, etc).

This proxy integration is suitable if your company:

  1. Wants full control of product operations.
  2. Have necessary technical expertise to keep up with all the 3 Product operations above.

The proxy integration sequence diagram looks like this:

As can be shown in the diagram, you will need to provide us one webhook API in to enable your agents to search and filter your product catalogue.

The data structure for both search and filter parameter and search and filter result will be discussed in the next section.

Aside from providing API for search and filter In addition, you will need to fill the Product setting page in your Prism Dashboard.

If you decide to use Proxy Integration, this section will explain the HTTP request that the Prism server send, and what HTTP response it does expect.

Search and Filter Request

When you provide Prism with webhook to search and filter your product catalogue, Prism will call that webhook using HTTP Post with request body specified below.

The data structure is loosely based on Elastic Search Bool Query, with following differences: 1. Minus the query.bool key. 2. Uses from and size for pagination.

Various samples of request body are provided below, but for further detail you can go to the Elastic Search documentation linked above.

  1. Minimalist search request, using "blue" as the query and getting result from first result (index 0) until 20.
{
  "from": 0,
  "size": 20,
  "must": [{ 
    "query_string": { 
      "query": "blue"   
    } 
  }]
}
  1. Minimalist filter request, with the assumption that you have field sku in your Product field.
{
  "from": 0,
  "size": 20,
  "filter": [{ 
    "term": { 
      "sku": "16" 
    } 
  }]
}
  1. Combination of search and filter.
{
  "from": 0,
  "size": 20,
  "must": [{ 
    "query_string": { 
      "query": "blue"   
    } 
  }],
  "filter": [{ 
    "range": {
      "weight": { 
        "gte": 1, 
        "lte": 1000 
      } 
    } 
  },{ 
    "term": { 
      "discount.discount_type": "percentage" 
    } 
  },{ 
    "term": { 
      "sku": "16" 
    } 
  }]
}

Product Data Structure

Prism expects specific data structure when calling your webhook. The data structure itself It's quite liberal.

Prism needs 4 things to be defined:

  1. Product ID.
  2. Product name.
  3. Product price.
  4. Product currency code.

Apart from those four mandatory fields, there are other optional fields that will be given special "treatment":

  1. Product description.
  2. Product image urls.
  3. Product stock/quantity.
  4. Product discount.

Format:

{
  "id": "<the_unique_product_id>",
  "name": "<the_product_name>",
  "price": "<the_product_price_in_string-formatted_decimal",
  "currency_code": "<iso_4217_code>",
  "description": "<the_product_description>",
  "image_urls": <array_of_image_url>,
  "stock": <the_product_quantity>,
  "discount": {
    "discount_type": "<NOMINAL_or_PERCENTAGE>",
    "amount": "<the_amount_of_nominal_or_percentage_in_string>"
  }
}

Note(s):

  • id (string, required): The product ID. This ID must be unique.
  • name (string, required): The name of the of the product.
  • price (string, required): The price of the product. Note that if this field doesn't exist, the price of the product will be considered as a free product.
  • currency_code (string, required): ISO 4217-compliant currency code.
  • image_urls (array of string, optional): The product images. This product images might be sent to the buyer via Prism Dashboard.
  • stock (long, optional): The number of product available in your inventory. Note that if this value doesn't exist, Prism Dashboard will consider this product to be always available.
  • discount (object, optional): The discount information of the product. Please note that if this field exists, then price and currency_code must exist, too.
  • discount.discount_type (string, required): There are two possible values: PERCENTAGE and NOMINAL, this value affects the discount type information.
    • if discount.discount_type == PERCENTAGE:
    • discount.amount (string, required): Decimal representation of the discount.
    • If discount.discount_type == NOMINAL:
    • discount.amount (string, required): The decimal amount of the price cut.

Valid Sample(s):

  1. Minimalist
{
  "id": "e7a4cdd4-8885-4255-be7a-9b680916288e",
  "name": "Flying Duck",
  "price": "100000",
  "currency_code": "IDR"
}
  1. With custom field. Note that the field harga will be ignored by Prism Dashboard and Prism Mobile.
{
  "id": "e7a4cdd4-8885-4255-be7a-9b680916288e",
  "name": "Flying Duck",
  "price": "100000",
  "currency_code": "IDR",
  "harga": "Rp 10000"
}
  1. Complete information. This will enable all UI for Product-related functionality on Prism.
{
  "id": "e7a4cdd4-8885-4255-be7a-9b680916288e",
  "name": "Flying Duck",
  "price": "100000",
  "currency_code": "IDR",
  "description": "Fresh hot flying duck",
  "image_urls": [
    "http://www.grahamowengallery.com/forum/mallard.jpg",
    "https://thumbs.dreamstime.com/x/flying-duck-8578253.jpg"
  ],
  "stock": 11
}
  1. Complete information, along with price-cut discount.
{
  "id": "e7a4cdd4-8885-4255-be7a-9b680916288e",
  "name": "Flying Duck",
  "price": "100000",
  "currency_code": "IDR",
  "description": "Fresh hot flying duck",
  "image_urls": [
    "http://www.grahamowengallery.com/forum/mallard.jpg",
    "https://thumbs.dreamstime.com/x/flying-duck-8578253.jpg"
  ],
  "stock": 11,
  "discount": {
    "discount_type": "NOMINAL",
    "amount": "12000"
  }
}
  1. Complete information, along with percentage discount.
{
  "id": "e7a4cdd4-8885-4255-be7a-9b680916288e",
  "name": "Flying Duck",
  "price": "100000",
  "currency_code": "IDR",
  "description": "Fresh hot flying duck",
  "image_urls": [
    "http://www.grahamowengallery.com/forum/mallard.jpg",
    "https://thumbs.dreamstime.com/x/flying-duck-8578253.jpg"
  ],
  "stock": 11,
  "discount": {
    "discount_type": "PERCENTAGE",
    "amount": "25.75"
  }
}

Request-Response Sample

Supposed that the webhook is located and registered at https://merchant-webhook.com/product-search, and the agent types "fish" in the product search text box:

Request that comes from Prism server goes to Merchant backend

  • HTTP method + URL: POST https://merchant-webhook.com/product-search
  • HTTP request body:
{
  "from": 0,
  "size": 10,
  "must": [
    {
      "query_string": {
        "query": "fish"
      }
    }
  ]
}

Expected response

Response should be wrapped inside JSend format.

  1. Successful response sample:

  2. HTTP status code: 200 (OK)

  3. HTTP content type: application/json
  4. HTTP response body:
{
  "status": "success",
  "data": {
    "total_hits": 1,
    "results": [
      {
        "id": "28885203-9b26-45cf-8c9e-ad6b25d43f19",
        "name": "Flying Fish",
        "price": "100000",
        "currency_code": "IDR",
        "description": "Fresh hot flying fish",
        "image_urls": [
          "http://ichef.bbci.co.uk/naturelibrary/images/ic/credit/640x395/f/fl/flying_fish/flying_fish_1.jpg"
        ],
        "stock": 11
      }
    ]
  }
}
  1. Failed response sample:

  2. HTTP status code: 404 (Not Found)

  3. HTTP content type: application/json
  4. HTTP response body:
{
  "status": "failed",
  "message": "Can't find product 'fish'"
}

In the above case, Prism Dashboard and Prism Mobile will show "Can't find product 'fish'" notification.

Shipping Integration

We are currently still finalizing this part, expect more to appear here :)

Checkout Integration

At Prism, we support two types of Checkout:

  1. Checkout without Integration
  2. Checkout with Integration

Checkout without Integration

Checkout without integration is fastest way to make sale instantly. Your agent only needs to fulfill all the needed detail to create an invoice.

Checkout with Midtrans’ VT-Web

We support Midtrans’ VT-Web out-of-the-box. All you need to do is inserting your Midtrans’ Server Key in the Dashboard.

Checkout With Integration

Since the first day of our development, Prism holds a principle to support your business flow however unique it might be. This principle has been shown in the Product Integration above, and it also applies to this Checkout Integration.

As of now, there are several steps which you can customize:

  1. Invoice creation
  2. Custom shipment
Invoice creation webhook

This is possibly the most important webhook. By using this webhook, you will be able to sync the invoice created in Prism to your system.

Format

Request that comes from Prism Server and goes to the webhook

  • HTTP method: POST
  • HTTP request body:
{
  "metadata": {
    "type": <the_name_of_webhook_type>,
    "version": <version_of_webhook_data_structure>
  },
  "data": {
    "order": <order_object>,
    "buyer": <buyer_object>,
    "shipment": <shipment_object>,
    "payment": <payment_object>
  }
}

Note(s)

  1. metadata will always be sent to the webhook.
  2. data.order will always be sent to the webhook.
  3. data.buyer, data.shipment, and data.payment are not guaranteed to be sent, it depends on its availability.
  4. For more complete documentation of order, buyer, shipment, and payment, please see Appendix A.

Expected response from the webhook (on succeeded)

  • HTTP status code: 2xx
  • HTTP content type: application/json
  • HTTP response body:
{
  "status": "success",
  "data": {
    "invoice": <invoice_object>
  }
}

For more complete documentation of invoice object, please see Appendix A.

Expected response from the webhook (on error)

  • HTTP status code: 4xx or 5xx
  • HTTP content type: application/json
  • HTTP response body:
{
  "status": "failed",
  "message": <error_explanation_in_string>
}
Invoice Webhook Request-Response Sample

Sample of request that comes from Prism Server and goes to the webhook

  • HTTP method + URL: POST https://merchant-webhook.com/create-invoice
  • HTTP request body:
{
  "metadata": {
    "type": "CREATE_INVOICE_FROM_ORDER",
    "version": 1
  },
  "data": {
    "order": {
      "id": "ORD-01BP1F017BYX3R0D525DCM1FK9",
      "line_items": [
        {
          "product": {
            "id": "e7a4cdd4-8885-4255-be7a-9b680916288e",
            "name": "Flying Duck",
            "price": "100000",
            "currency_code": "IDR"
          },
          "quantity": 1
        }
      ],
      "status": "DRAFT"
    },
    "buyer": {
      "name": "Buyer",
      "email": "[email protected]",
      "phone_number": "08123456789"
    },
    "shipment": {
      "cost": {
        "currency_code": "IDR",
        "amount": "1000"
      }
    },
    "payment": {
      "provider": {
        "type": "transfer",
        "transfer": {
          "account_number": "11561156",
          "account_holder": "PT Koneksi",
          "bank_name": "BCA"
        }
      }
    }
  }
}

Sample of expected response from the webhook (on succeeded)

  • HTTP status code: 201 (Created)
  • HTTP content type: application/json
  • HTTP response body:
{
  "status": "success",
  "data": {
    "invoice": {
      "id": "INV-01BP1F017BYX3R0D525DCM1FK9",
      "status": "ISSUED",
      "line_items": [
        {
          "product": {
            "id": "e7a4cdd4-8885-4255-be7a-9b680916288e",
            "name": "Flying Duck",
            "price": "100000",
            "currency_code": "IDR"
          },
          "quantity": 1
        }
      ],
      "shipment": {
        "choice": {
          "id": "JNE-REG",
          "name": "JNE Reguler (2 days)"
        }
        "cost": {
          "currency_code": "IDR",
          "amount": "100"
        },
        "provider": {
          "type": "custom",
          "custom": {
            "<merchant_specific_field_1>": "<merchant_specific_field_value_1>",
            "<merchant_specific_field_2>": "<merchant_specific_field_value_2>",
            "<merchant_specific_field_n>": "<merchant_specific_field_value_n>"
          }
        }
      },
      "payment": {
        "provider": {
          "type": "transfer",
          "transfer": {
            "account_number": "4371111111",
            "account_holder": "Ducky Duck Corp",
            "bank_name": "BCA"
          }
        }
      },
      "grand_total": {
        "currency_code": "IDR",
        "amount": "100100"
      }
    }
  }
}

Sample of expected response from the webhook (on error)

  • HTTP status code: 400 (Bad Request)
  • HTTP content type: application/json
  • HTTP response body:
{
  "status": "failed",
  "message": "Product 'Flying Duck' is out of stock"
}

In the above case, Prism Dashboard and Prism Mobile will show "Product 'Flying Duck' is out of stock" notification.

Search Shipment Area webhook

This webhook will be used to determine the area that you support.

Format

Request that comes from Prism Server and goes to the webhook

  • HTTP method: GET
  • HTTP query param name: name

Expected response from the webhook (on succeeded)

  • HTTP status code: 2xx
  • HTTP content type: application/json
  • HTTP response body:
{
  "status": "success",
  "data": {
    "shipment_areas": [<array_that_contains_shipment_area_objects>]
  }
}

For more complete documentation of shipment_area, please see Appendix A.

Expected response from the webhook (on failed)

  • HTTP status code: 4xx or 5xx
  • HTTP content type: application/json
  • HTTP response body:
{
  "status": "failed",
  "message": <error_explanation_in_string>
}
Search Supported Shipment Area Request-Response Sample

Sample of request that comes from Prism Server and goes to the webhook

  • HTTP method + URL: GET https://merchant-webhook.com/search_shipment_area?name=kebayoran&provier=custom

Sample of expected response from the webhook (on succeeded)

  • HTTP status code: 200 (OK)
  • HTTP content type: application/json
  • HTTP response body:
{
  "status": "success",
  "data": {
    "shipment_areas": [
      {
        "label": "Kebayoran Baru, Kota Administrasi Jakarta Selatan, DKI Jakarta",
        "provider": "custom",
        "custom": {
          "country": "IDN",
          "first_level": "DKI Jakarta",
          "second_level": "Kota Administrasi Jakarta Selatan",
          "third_level": "Kebayoran Baru"
        }
      },
      {
        "label": "Kebayoran Lama, Kota Administrasi Jakarta Selatan, DKI Jakarta",
        "provider": "custom",
        "custom": {
          "country": "IDN",
          "first_level": "DKI Jakarta",
          "second_level": "Kota Administrasi Jakarta Selatan",
          "third_level": "Kebayoran Lama"
        }
      }
    ]
  }
}

Sample of expected response from the webhook (on failed)

  • HTTP status code: 404 (Not Found)
  • HTTP content type: application/json
  • HTTP response body:
{
  "status": "failed",
  "message": "'kebayoran' is not supported."
}
Get Shipment Choices webhook

Given a supported shipment area, this webhook will be used to determine the shipment choices for that area.

Request that comes from Prism Server and goes to the webhook

  • HTTP Method + URL: POST https://merchant-webhook.com/shipment-choices
  • HTTP Request body:
{
  "metadata": {
    "type": <prism_specific_type>,
    "version": <version_of_the_data_structure>
  },
  "data": {
    "cart": <cart_object>,
    "shipment_area": <shipment_area_object>
  }
}

Note(s)

  1. metadata will always be sent to the webhook.
  2. data.cart and data.shipment_area will always be sent to the webhook.
  3. data.buyer, data.shipment, and data.payment are not guaranteed to be sent, it depends on its availability.
  4. For more complete documentation of cart and shipment_area please see Appendix A.

Expected response from the webhook (on succeeded)

  • HTTP status code: 2xx
  • HTTP content type: application/json
  • HTTP response body:
{
  "status": "success",
  "data": {
    "shipment_choices": [<array_that_contains_shipment_area_objects>]
  }
}

For more complete documentation of shipment_choices, please see Appendix A.

Expected response from the webhook (on error)

  • HTTP status code: 4xx or 5xx
  • HTTP content type: application/json
  • HTTP response body:
{
  "status": "failed",
  "message": <error_explanation_in_string>
}
Get Shipment Choices Request-Response Sample:

Sample of request that comes from Prism Server and goes to the webhook

  • HTTP Method + URL: POST https://merchant-webhook.com/get_shipment_choices
  • HTTP Request body:
{
  "metadata": {
    "type": "GET_CUSTOM_SHIPMENT_CHOICES",
    "version": 1
  },
  "data": {
    "cart": {
      "line_items": [
        {
          "product": {
            "id": "e7a4cdd4-8885-4255-be7a-9b680916288e",
            "name": "Flying Duck",
            "price": "100000",
            "currency_code": "IDR"
          },
          "quantity": 1
        }
      ]
    },
    "shipment_area": {
      "label": "Kebayoran Baru, Kota Administrasi Jakarta Selatan, DKI Jakarta",
      "provider": "custom",
      "custom": {
        "country": "IDN",
        "first_level": "DKI Jakarta",
        "second_level": "Kota Administrasi Jakarta Selatan",
        "third_level": "Kebayoran Baru"
      }
    }
  }
}

Sample of expected response from the webhook (on succeeded)

  • HTTP status code: 200 (OK)
  • HTTP content type: application/json
  • HTTP response body:
{
  "status": "success",
  "data": {
    "shipment_choices": [
      {
        "id": "10001",
        "label": "JNE REG 2 hari",
        "cost": {
          "currency_code": "IDR",
          "amount": "10000"
        }
      },
      {
        "id": "10002",
        "label": "JNE YES 1 hari",
        "cost": {
          "currency_code": "IDR",
          "amount": "18000"
        }
      }
    ]
  }
}

Sample of expected response from the webhook (on error)

  • HTTP status code: 400 (Bad Request)
  • HTTP content type: application/json
  • HTTP response body:
{
  "status": "failed",
  "message": "No shipment choices for 'Kebayoran Baru, Kota Administrasi Jakarta Selatan, DKI Jakarta'."
}

Appendix A: Checkout Data Structures

1. Common Data Structure

1.1. Money

Money represents, well, money. This data structure should be able to represent most currencies in the world.

Format:

{
  "currency_code": "<iso_4217_code>",
  "amount": "<decimal>"
}

Note(s):

  • Both currency_code and amount are mandatory.
  • The amount needs to be in String datatype to overcome Javascript deficiencies when handling number.

Sample(s):

{
  "currency_code": "IDR",
  "amount": "10000000"
}

1.2. Discount

Discount represent price cut.

Format:

{
  "type": "<discount_type>",
  "<discount_type>": "<discount_type_info>"
}

There are two discount types:

  1. Percentage
  2. Price

Format for discount type percentage:

{
  "type": "percentage",
  "percentage": <string_format_of_percentage>
}

Format for discount type price:

{
  "type": "price",
  "price": <money_object>
}

Note(s):

  • All fields are mandatory

Sample(s):

Sample(s) for percentage:

{
  "type": "percentage",
  "percentage": "25.5"
}

Sample(s) for price:

{
  "type": "price",
  "price": {
    "currency_code": "IDR",
    "amount": "100000"
  }
}

1.3. Product

Product represents something the Buyer wants to buy. This is the same the one explained above.

1.4. Line Item

Line Item represent an Item in the Cart, in the Order, and in the Invoice.

Format:

{
  "product": <product_object>,
  "quantity": <integer>
}

Note(s):

  • product and quantity are mandatory.

Sample(s):

{
  "product": {
    "id": "e7a4cdd4-8885-4255-be7a-9b680916288e",
    "name": "Backstreet Boys Collection",
    "price": "100000",
    "currency_code": "IDR"
  },
  "quantity": 2
}

2. Main Data Structure

2.1. Buyer Data

Buyer Data contains various information about the Buyer's.

Format:

{
  "name": "<buyer_name>",
  "email": "<buyer_email>",
  "phone_number": "<buyer_phone_number>"
}

Note(s):

  • All fields are optional

Sample(s):

{
  "name": "Someone",
  "email": "[email protected]",
  "phone_number": "1234567890"
}

2.2. Cart

Cart contains list of Line Items that the Buyer intends to buy.

Format:

{
  "line_items": [<line_item_01>, .., <line_item_n>]
}

Sample(s):

{
  "line_items": [{
      "product": {
        "id": "e7a4cdd4-8885-4255-be7a-9b680916288e",
        "name": "Backstreet Boys Collection",
        "price": "100000",
        "currency_code": "IDR"
      },
      "quantity": 2
    },
    {
      "product": {
        "id": "616e53c9-802b-486c-9d33-25e09de2ec0e",
        "name": "The Best of A*Teens",
        "price": "200000",
        "currency_code": "IDR"
      },
      "quantity": 5
    }
  ]
}

2.3. Order

Order will be generated when the Buyer place an Order to the Seller.

Format:

{
  "id": "<order_id>",
  "status": "<DRAFT_or_PLACED>",
  "line_items": [<line_item_01>, .., <line_item_n>]
}

Note(s):

  • All fields are required.
  • Order's status is DRAFT when Buyer is permitted to change it. When the Order is PLACED, it can no longer be modified.

Sample(s):

{
  "id": "ORD-01B8D75GJ5HYH80P48PENC0VDF",
  "status": "PLACED",
  "line_items": [
    {
      "product": {
        "id": "e7a4cdd4-8885-4255-be7a-9b680916288e",
        "name": "Backstreet Boys Collection",
        "price": "100000",
        "currency_code": "IDR"
      },
      "quantity": 2
    },
    {
      "product": {
        "id": "616e53c9-802b-486c-9d33-25e09de2ec0e",
        "name": "The Best of A*Teens",
        "price": "200000",
        "currency_code": "IDR"
      },
      "quantity": 5
    }
  ]
}

2.4. Invoice

Invoice represent a request from Seller to Buyer to perform payment based on previously placed Order.

Format:

{
  "id": "<invoice_id>",
  "status": "<ISSUED_or_PAID>",
  "line_items": [<line_item_object_01>, .., <line_item_object_n>],
  "grand_total": <money_object>,
  "payment": <payment_object>,
  "shipment": <shipment_object>
}

Note(s):

  • id, status, line_items, grand_total, and payment are required. The rest are optional.
  • Invoice's status is ISSUED when the Invoice is generated, and it becomes PAID when the Buyer has paid for it.
  • payment and shipment description is still TODO, pending its Nodes development.

Sample(s):

{
  "id": "INV-01B8D75GJ5HYH80P48PENC0VDF",
  "status": "ISSUED",
  "line_items": [
    {
      "product": {
        "id": "e7a4cdd4-8885-4255-be7a-9b680916288e",
        "name": "Backstreet Boys Collection",
        "price": "100000",
        "currency_code": "IDR"
      },
      "quantity": 2
    },
    {
      "product": {
        "id": "616e53c9-802b-486c-9d33-25e09de2ec0e",
        "name": "The Best of A*Teens",
        "price": "200000",
        "currency_code": "IDR"
      },
      "quantity": 5
    }
  ],
  "grand_total": {
    "currency_code": "IDR",
    "amount": "1200000"
  }
}

2.5. Voucher

Voucher represents something that usually used by the buyer to reduce the price of the Cart or Order.

Format:

{
  "code": "<the_voucher_code>",
  "status": "<one_of_voucher's_status>",
  "description": "<voucher's_description>"
}

Note(s):

  • code and status are required. description is optional.
  • Status must be one of the following:

    • UNCHECKED: when the voucher is not yet checked by the merchant.
    • VALIDATED: signify that voucher is indeed a valid voucher.
    • APPLIED: the voucher is applied. Subsequent application of voucher may yield ALREADY_APPLIED.
    • ALREADY_APPLIED: the voucher is no longer valid because it has been applied in the past.
    • NOT_FOUND: the voucher is not valid because it has never been registered as a valid voucher..
    • EXPIRED: the voucher was valid, but now expired.
    • REQUIREMENTS_NOT_MET: The voucher does not met the requirements.

Sample(s):

{
  "code": "CODE1234",
  "status": "APPLIED"
}
{
  "code": "OLDIESROCK",
  "status": "APPLIED",
  "description": "Oldies music fan appreciation."
}
{
  "code": "RNADOM",
  "status": "NOT_FOUND"
}

2.6. Shipment Address

Shipment address represent the buyer's specific address.

Format:

{
  "full_street": <string_that_contains_buyer's_specific_address>,
  "postal_code": <buyer's_postal_code>
}

Note(s):

  • full_street is required, postal_code is optional.

2.7. Shipment Area

Shipment area will be used to identify the supported shipment area.

Format:

{
  "label": <the_label_to_shown_in_the_UI>,
  "provider": <the_shipment_area_provider>,
  <provider>: <provider_specific_information>
}

Note(s):

  • All keys are required.
  • label must contain string that meaningful to be shown in the UI.
  • If provider is custom. It must contain keys:
  • country(required) : The country of the shipment, in ISO-3661 Alpha-3.
  • first_level (required) : The first administrative level. As specified in https://en.wikipedia.org/wiki/List_of_administrative_divisions_by_country
  • second_level (optional).
  • third_level (optional).

2.8. Shipment Choice

Shipment choice represent choice of shipment package offered by a shipment provider.

Format:

{
  "id": <the_identifier_for_shipment_choice>,
  "label": <name_to_be_shown_in_the_ui>,
  "cost": <money_object_that_represents_how_much_shipment_provider_charges>
}

Note(s):

  • id and label are required, cost is optional. If cost is empty, Prism will assume that the shipment cost for this choice is free.
  • label should be filled using value that clear from Agent's point of view.

2.9. Shipment

Shipment represent various information about Shipment.

Format:

{
  "address": <shipment_address_object>,
  "cost": <money_object>,
  "area": <shipment_area_object>,
  "provider": <shipment_provider_specific_information>,
  "choice": <shipment_choice_object>,
  "info": <additional_information>
}

Note(s):

  • One of cost or provider are required, the rest are optional.
  • If provider is present. It must contain keys:
  • type: The provider type.
  • <provider_type>. This key contains provider-specific information.
  • Currenly, Prism supports following Shipment Provider:
  • Epeken
    • For Epeken, following fields are required:
    • kabupaten: The name of the kabupaten. This info is provided from TuanTanah.
    • kecamatan: The name of the kecamatan. This info is provided from TuanTanah.
  • Agenwebsite
    • For Agenwebsite, following fields are required:
    • provinsi: The name of the provinsi. This info is provided from TuanTanah.
    • kota: The name of the kabupaten. This info is provided from TuanTanah.
    • kecamatan: The name of the kecamatan. This info is provided from TuanTanah.
    • This following field are optional:
    • kodepos: The kode pos number. This is NOT provided by TuanTanah. If this field is provided, then shipment choices offered PT Pos Indonesia will be included.
  • Custom.
    • The content for this key will be controlled by Prism's merchant.

Sample(s):

{
  "cost": {
    "currency_code": "IDR",
    "amount": "10000"
  }
}
{
  "provider": {
    "type": "epeken",
    "epeken": {
      "kabupaten": "Kabupaten Sleman",
      "kecamatan": "Cangkringan"
    }
  }
}
{
  "cost": {
    "currency_code": "IDR",
    "amount": "10000"
  },
  "provider": {
    "type": "epeken",
    "epeken": {
      "kabupaten": "Kabupaten Sleman",
      "kecamatan": "Cangkringan"
    }
  }
}
{
  "cost": {
    "currency_code": "IDR",
    "amount": "10000"
  },
  "provider": {
    "type": "agenwebsite",
    "agenwebsite": {
      "provinsi": "Daerah Istimewa Yogyakarta",
      "kota": "Kab. Bantul",
      "kecamatan": "Dlingo"
    }
  }
}
{
  "cost": {
    "currency_code": "IDR",
    "amount": "10000"
  },
  "provider": {
    "type": "agenwebsite",
    "agenwebsite": {
      "provinsi": "Daerah Istimewa Yogyakarta",
      "kota": "Kab. Bantul",
      "kecamatan": "Dlingo",
      "kodepos": "55282"
    }
  }
}

2.10. Payment

Payment contains information about payment information.

Format:

{
  "provider": <payment_provider_specific_information>
}

Note(s):

  • provider and provider.type are mandatory.
  • Based on the content of provider.type, dynamic key based on the provider.type's value can appear, with the rule as follows:
  • If provider.type is cod (cash on delivery), then there are no dynamic key.
  • If provider.type is transfer, dynamic key transfer is required, with following content:
    • account_number: (Mandatory) The number to identify the account. Provided by the bank.
    • account_holder: (Optional) The name of the account holder.
    • bank_name: (Mandatory) The bank name
  • If provider.type is vt_web, dynamic key vt_web can appear optionally. If it does appear, the folloing is required:
    • redirect_url: (Mandatory) The URL for the buyer to continue payment.
  • If provider.type is payment_link, dynamic key payment_link is required, with following content:
    • id: (Mandatory) The identifier for payment link type.
    • label: (Optional) The label for this payment link. This will be used in the UI.
    • url: (Optional) The URL for the payment.

Sample(s):

{
  "provider": {
    "type": "cod"
  }
}
{
  "provider": {
    "type": "transfer",
    "transfer": {
      "account_number": "1234567890",
      "account_holder": "Nick Carter",
      "bank_name": "BCA"
    }
  }
}
{
  "provider": {
    "type": "vt_web",
    "vt_web": {
      "redirect_url": "https://www.google.com"
    }
  }
}
{
  "provider": {
    "type": "payment_link",
    "payment_link": {
      "id": "AWESOME_PAYMENT",
      "label": "Awesome Payment",
      "url": "https://www.google.com"
    }
  }
}

Disclaimer

Please note that this document will be updated frequently, we will have the online version at the soonest and will gladly share the link to you

If you have any queries, please don’t hesitate to contact us at [email protected]