User Guide | Proxtera

User Guide

 

Disclaimer

This Document has been prepared by Proxtera Pte. Ltd. (“Proxtera”) and is intended for general information purposes only and does not constitute the rendering of any advice, recommendation, solicitation, offer, or service. This Document has been prepared based on information made available up to the date of this Document. No representation or warranty, express or implied, is made as to the accuracy, authenticity, completeness or fairness of the information or opinions contained in this Document, and any responsibility or liability for any such information or opinions is expressly disclaimed.

This Document is provided on the basis that Proxtera accepts no liability – whether in contract, tort (including negligence), or otherwise – to you or to any other person in respect of this Document.

This Document must not be made available or copied in whole or in part to any other person without Proxtera’s express written permission.

Audience

Technology/Engineering/Product teams from B2B platforms

Introduction

Welcome to the Proxtera User Guide. We have designed this guide to walk you through the integration process with Proxtera’s APIs and provide you with insight into our Testing environment and the best way to navigate it.

Proxtera’s Products

Proxtera Connect Proxtera Protect Fulfillment (Coming Soon) Payments (Coming Soon) Financing (Coming Soon)
Seamlessly connect your end users to new buyers and suppliers from other marketplaces that are part of the Proxtera Network Digital escrow services to enhance security and trust when transacting over the Proxtera Network 3PL Providers can access global trade environments to carry out logistics processes for end users Provide Payments services to facilitate ease of cross-border transactions Enables financing service providers to provide trade financing options to end users

 

 

Understand Product Flow

Please look through our process flow to acquaint yourself with our process.

Proxtera Portal:

The Proxtera Portal consists of the User Acceptance Testing (UAT) and the Production environment.

 

Homepage

Upon logging in you will be directed to your Dashboard.
You will see two messages.

The message on the left is to look through the API keys and identify which APIs your platform would like to integrate with.

The message on the right prompts you to complete your Company Profile.

The information that you have already submitted, i.e Company Name, Company URL will be pre-filled.

We recommend filling out your Company Profile because it provides Proxtera with more insight on your platform and how we can help your platform garner more trades.

 

User Profile

Kindly also fill out the User Profile.

Features of Testing Environment:

The features offered on the Proxtera Portal are similar in both the UAT and Production environments:

Home page: On this page you will see an overview of

  • Uploaded catalogues

  • The number of SMEs from your platform who have opted into Proxtera

  • Uploaded categories

SME List

Under this tab, you can add and maintain the list of SMEs on your platform who have opted in to Proxtera.

Invite Team Members

This feature allows you (the admin) to invite more team members to access the Proxtera portal.

The invitation process is similar to the initial invitation sent to the platform admin to sign-up. It will be in the invitee’s email and include a link to proceed toward signing up to the portal.

API Integration

This feature enables you to request for and generate client IDs and API keys. The sign-in password is required to generate the API keys and Client IDs.

Access to API documentation for Proxtera APIs

This feature is a link to the API documentation with Proxtera’s APIs. It also provides the URLs for the endpoints required to be connected for each API (in the UAT and Production environments respectively).

UAT Progess

Under this tab, you will be able to review your Integration Progress as well as submit queries and evidence of passing relevant test cases.

UAT Progress Page

Query and Test Evidence Submission

 

Connect to Proxtera API Endpoints

API Documentation
Before connecting to the APIs, please look through our API documentation to view Proxtera’s APIs, as well as the URLs for the endpoints required to be connected for each API (in the UAT and Production environments respectively).

The API endpoints that need to be integrated with your platform differ based on whether your platform is a Buyer or Seller platform or both. Please look at the table below to determine which endpoints your platform needs to connect to.

API Keys Buyer Seller Both
Search


Platform searches Proxtera


Proxtera searches Platform


Proxtera searches Platform and
Platform searches Proxtera

SME

Create Purchase Order (PO)

Not required

Confirm Purchase Order (PO)

Not required

Create Invoice

Not required

Accept Invoice

Not required

Send Remittance Advice

Update Shipping Status

SME Platform (Webhook)

Send Message

Escrow Platform

Send GRN

Financing

Document Locking

OAuth 2.0 Authentication
All Proxtera API’s are authorized using the OAuth2.0 token. With OAuth 2.0, you first retrieve an access token for the API, then use that token to authenticate future requests. This token needs to be refreshed every 30 minutes due to the standard protocol.

Please find the official Postman OAuth 2.0 token generation documentation.

A step by step manual with screenshots is available below.

Step 1:- Collect API keys and API config

Generate the Client Id and Client Secret under the API Integration section of our portal. Make sure to save a copy of Client Secret in your local place.

 

Step 2:- Create OAuth 2.0 token in Postman

  1. Under the Authorization tab, select the ‘Type’ as OAuth 2.0 and set ‘Add authorization data to’ field as Request Header.
  2. Under the Configure New Token, fill in the required details.
    Field Name Value
    Token Name The name of token.(For example:- Buyer Platform)
    Grant Type Set this field as client Credentials.
    Access Token URL The token URL collected from API Integration section of our portal.(For example:- https://sso.uat.proxtera.app/oauth2/token)
    Client ID The Client ID collected from API Integration section of our portal.
    Client Secret The Client Secret collected from API Integration section of our portal.
    Client Authentication Set this field as ‘Send as Basic Auth header’.
  1. Select the newly configured Token, under the Current Token section.

2. You are now good to go for an API hit. For example, if you want to test the smart-search endpoint.

 

UAT Progress

Please refer to the API Documentation while conducting the API Integration.

Search API

This API Integration involves connecting the Search Endpoint which will allow your platform to search and view the results available on Proxtera’s connected platforms and vice versa where Proxtera is able to search and view the results available from your platform.

Search (Platform Search Proxtera) API

Evidence to be submitted: A screenshot of a Search conducted on Platform.

PASS: The Search results display Products available through Proxtera
FAIL: The Search results do not display any Proxtera results

Search (Proxtera Search Platform)

Once the Endpoint has been connected, please click on the SUBMIT FOR VERIFICATION button, Proxtera will conduct a test on our end to check if the integration has been successful.

PASS: Proxtera is able to conduct a search and view the products from platform and no fields are returned as null.
FAIL: Proxtera is unable to view products from platform and/or certain fields are returned as null.

SME Endpoint

Register SME to the Proxtera platform.

PASS: SME is successfully registered.
FAIL: Request for registration is incorrect/SME already exists.

Purchase Order

Create Purchase Order

This API Endpoint is to create a purchase order. Once you have connected to the API Endpoint and sent the post request please click the SUBMIT FOR VERIFICATION button. Proxtera will conduct a test on our end to check if the integration has been successful.

PASS: Platform is able to create and send a purchase order to Proxtera.
FAIL: Platform is unable to successfully send a purchase order to Proxtera (e.g Request is incorrect or malformed)

Confirm Purchase Order

This API Endpoint is to confirm a purchase order. Once you have connected to the API Endpoint and sent the post request please click the SUBMIT FOR VERIFICATION button. Proxtera will conduct a test on our end to check if the integration has been successful.

PASS: Platform is able to confirm the purchase order received.
FAIL: Platform is unable to confirm the purchase order received

Invoice

Create Invoice

This API Endpoint is to create an invoice for payment of purchase order. Once you have connected to the API Endpoint and sent the post request please click the SUBMIT FOR VERIFICATION button. Proxtera will check on our end to confirm if the integration has been successful.

PASS: Platform is able to create and send an invoice successfully.
FAIL: Platform is unable to create an invoice (e.g request is incorrect)

Accept Invoice

This API Endpoint is to create an invoice for payment of purchase order. Once you have connected to the API Endpoint and sent the post request please click the SUBMIT FOR VERIFICATION button. Proxtera will check on our end to confirm if the integration has been successful.

PASS: Platform is able to communicate the acceptance of an invoice successfully.
FAIL: Platform is unable to communicate the acceptance of an invoice.

Remittance

Send Remittance Advice

This API Endpoint is to send remittance advice to a seller platform. Once you have connected to the API Endpoint and sent the post request please click the SUBMIT FOR VERIFICATION button. Proxtera will check on our end to confirm if the integration has been successful.

PASS: Connect to the API Endpoint and send a remittance advice successfully.
FAIL: Unable to send a remittance advice

Shipment

Update Shipment Status

This API Endpoint allows a seller to update the delivery status of a shipment. Once you have connected to the API Endpoint and sent the post request please click the SUBMIT FOR VERIFICATION button. Proxtera will check on our end to confirm if the integration has been successful.

PASS: Send shipment status updates successfully.
FAIL: Unable to send shipment status updates (e.g Required fields are null)

SME Platform (Webhook)

This endpoint enables real-time international messaging and negotiation capabilities within the platform native messaging flow. Once you have connected to the API Endpoint and sent the post request please click the SUBMIT FOR VERIFICATION button. Proxtera will check on our end to confirm if the integration has been successful.

PASS: Able to receive message updates. 
FAIL: Unable to receive message updates

Messaging

Send Message

This feature is intended to connect to the platform chat functionality for seamless messaging across participating platforms. Once you have connected to the API Endpoint and sent the post request please click the SUBMIT FOR VERIFICATION button. Proxtera will check on our end to confirm if the integration has been successful.

PASS: Connect successfully to the API Endpoint to enable messaging between platforms.
FAIL: Connection unsuccessful (e.g No messages match the filter criteria) 

Non-Repudiation

Non-Repudiation is used to prove the identity of the sending party, providing protection against compromised authentication credentials and malicious attempts to imitate the sender of the message. We want to ensure that the sender cannot deny having sent the message; e.g. a bank cannot deny having sent a bank statement if it has a valid stamp of the bank on it and this could be proved to a third party.

In the Proxtera ecosystem, while all endpoints are secure using TLS and OAuth2 authentication, certain endpoints are more carefully guarded and require all messages to those support non-repudiation protocols.

Procedure WITH Non-Repudiation

  1. The sender will generate a 2048 bit RSA-2 key-pair and submit the public key on the Proxtera portal.
  2. The sender loads the complete payload in the JWT token (as shown in the above create PO Example) and signs it with their private key (from the key-pair in step 1).
  3. The signed JWT will be sent in the request header using key “X-Signed” and base64 encoding.
  4. Proxtera will use the public key to validate the JWT signature and claims, then validate the payload against the provided claims. This complete flow of validations happens in three steps, and the artefacts from each are stored:
    1. Proxtera stores the signed JWT and payload in the database that is received in step 3.
    2. Proxtera verifies the JWT using the public key submitted by the platform in step 1. The verified payloads are stored in the database.
      1. Note that Proxtera is using the sender’s own self-submitted public key to verify the message; this step cannot be completed unless the message was signed by the sender using their private key. This is irrefutable proof that the message came from the sender.
    3. Proxtera validates the payload against the provided claims. The validation results are stored in the database (in addition to the usual request metadata).
    4. All the items in steps a, b and c above are stored in the database, tagged by the date, relevant order_id or another type of id.

Example – Create PO Payload JWT claims (subset for signing):

{
	"platform_id": "string-uuidv4",
	"buyer_id": "string",
	"buyer_tax_id": "string",
	"seller_id": "string-uuidv4",
	"seller_tax_id": "string",
	"order_id": "string",
	"item_count": 3,
	"incoterms": "FOB",
	"payment_method": "ProxteraProtect",
	"sub_total": "150000",
	"currency": "USD",
	"order_date": "20211002",
	"timestamp": "2021-10-02T15:04:05Z07:00",
	"shipping_info": {
		"address": "string",
		"addressee_name": "string",
		"contact_info": {
			"email": "string",
			"phone": "string"
		},
		"corporate_name": "string",
		"tax_id": "string"
	},
	"items": {
		"name": "string",
		"product_id": "string",
		"quantity": "string",
		"unit_measure": "string",
		"unit_price": {
			"amount": "string",
			"currency": "string"
		}
	}
}

Singed JWT token generated with the above subset of payload:-

MzMW3YFi/13TZH4zDLx4nCXiles5Pljmw2FQL+qN7xqPZ/mU+Wj9D6v58jhHmimPmF6FcyRftB36yRUX2mMXX0KOa0P+0wQdACdBx4fKiceQHFAabymfUr/xkKpnOMzg+r8HmiyQWkNTJjsfvIJe72hXbT+4l/vZKp0vsk2gASpvg9M4M32TCAMLtWLg8J/XLz+hPUCow8WFRJqSEkgk/vHEfuLGhtNOpCcrK5NByqm2RSdcBG2WgIeu0uRXa8tAGOB05DxAYogQ0lW7EiP33hypo6h3Q+jDcaw6u7XtVWCD6qCQXBdWQgzG3t1jBn/pUrGx3WEOcucYmD18JfJ8wQ==

The signed payload is sent in the header using key “X-Signed” and base64 encoding. Please note all the fields send during the procedure without non-repudiation are still sent with one extra field “X-Signed” with the signed JWT token as the value.

Exception framework for data fields

This exception framework was created to aid platforms in their integration with Proxtera. If you are unable to match the data field requirements you can use this table to manage the anomalies.

The table below covers the anomalies faced with certain platforms when ‘Proxtera searches them’:

Anomaly Description Generic Solution Example
Placing Default Values for a mandatory field Some platforms are unable to return the expected values (as mentioned in Proxtera swaggers) for the mandatory field(s) in the search response. The is usually because they are using the same search API to render their platform’s own user interface and adding/changing fields in existing API’s will disturb/break their product flow. The solution for this problem is to provide some default value to that field in the Proxtera wrapper. For one of the mandatory fields, Platform ABC is not able to return is “export_destinations”, but agreed on setting the default value to this field as ‘worldwide’. Thus every product from Platform ABC will be returned to the buyer platform after adding the field export_destinations.
Creating Lookups For some, the mandatory field that platforms are not capable of returning but also does not have static fields creates another anomaly. The solution for this problem is a lookup table or API (provided by the seller platform) Platform EFG is not able to return one of the mandatory fields ‘category.type‘ and ‘category.code‘, instead they have requested a lookup from their Endpoint.
Platform does not store relevant information for mandatory field(s) For some mandatory field(s), platform does not capture relevant information.

The solution for this problem is to ask for a more generic value for such fields:-

  1. N/A (Not Available)
  2. POR (Provide On Request).
Platform XYZ is not able to return one of the mandatory fields ‘packaging_size‘, So they return ‘N/A’ for that field.

Anomaly Replacement Framework – Search Results

Field

Required (Yes/No)

Behaviour if absent

Replacement value

category.type

Yes

Replace

N/A

category.code

Yes

Replace

N/A

description

Yes

Replace

POR

estimated_shipping_time

No

None

export_destinations

Yes

Replace

Worldwide

feedback_widget

Yes

images

No

incoterms.code

Yes

Replace

EXW

incoterms.deliver_to

Yes

Replace

Platform native place

lead_time

No

None

main_image

No

None

manufacturer_info.corporate_name

No

None

manufacturer_info.address.address

No

None

manufacturer_info.address.city

No

None

manufacturer_info.address.country

No

None

manufacturer_info.address.postal_code

No

None

manufacturer_info.address.state

No

None

minimum_qty

No

None

minimum_qty_dimension

No

None

minimum_qty_weight

No

None

name

Yes

Non-Negotiable

negotiable

Yes

Replace

POR

packaging_size

Yes

Replace

POR

payment_method

Yes

Replace

Proxtera Protect

payment_terms

No

None

product_id

Yes

Non-negotiable

seller_id

Yes

Non-negotiable

Supplier Info End-point needed

seller_info.corporate_name

Yes

Non-negotiable

Supplier Info End-point needed

seller_info.tax_id

Yes

Non-negotiable

Supplier Info End-point needed

seller_info.address.address

Yes

Non-negotiable

Supplier Info End-point needed

seller_info.address.city

Yes

Non-negotiable

Supplier Info End-point needed

seller_info.address.state

Yes

Non-negotiable

Supplier Info End-point needed

seller_info.address.postal_code

Yes

Non-negotiable

Supplier Info End-point needed

seller_info.address.country

Yes

Non-negotiable

Supplier Info End-point needed

seller_info.contact_info.phone

Yes

Non-negotiable

Supplier Info End-point needed

seller_info.contact_info.email

No

seller_terms

No

type

Yes

Replace

Product

unit_dimension

No

unit_measure

Yes

Non-negotiable

unit_price.amount

Yes

Non-negotiable

unit_price.currency

Yes

Non-negotiable

unit_weight

No

unit_weight_measure

No

 

Pass Test Cases and Provide Evidence

Evidence will be shared through the built-in chat function under the UAT Progress page.

This is the built-in chat function that allows you to submit queries and test API endpoint verification by clicking on the SUBMIT FOR VERIFICATION button.

Submitting Evidence for API endpoint verification.

 

 

Access to Production

Access to the Production environment will be granted via email after successful integration with the relevant API Endpoints.

  • All test cases in UAT are passed and evidence has been provided

Troubleshooting/FAQ

For technical issues with integration, please follow the link here to raise an issue through the help centre.