Chapter 4 - Quick Start Guide for AppLink USA Web API

 

The AppLink Web API provides a Developer Portal that utilizes the Swagger Open Source environment UI to provide a testing environment – a Sandbox. The web interface (UI) for the Sandbox is the Swagger Open API tool. The Sandbox provides for testing and experimentation with the AppLink Web API. The Sandbox is intended to provide a way to quickly test how the Merchant “payload” and documents are submitted using the AppLink Web API and the type of responses the API may return.

IMPORTANT: The Sandbox IS NOT intended to be an example of how you would use the AppLink Web API in YOUR production environment. The use of the API in production will require YOU, the developer, to determine how to retrieve the required information from your internal systems and processes then provide that “payload” of information in the proper format along with the supporting documents to the AppLink Web API. Your developed application and processes will also need to handle the API’s various responses to a submission in order to complete the Merchant Application. How each partner uses the API and provides the required information is up to each partner to design to fit their organization’s needs.

This quick start below uses the AppLink Web API basic process described in the section “Overview of the AppLink Web API process” with the Swagger UI to demonstrate how the API operations work and what each operation requires. This quick start utilizes the available API operations through the Swagger UI to submit the Merchant application data (“payload”) and supporting document utilizing the AppLink Web API. 

To utilize the Sandbox in this example you use a “Shared Test api_key” test:Testing123$, the example payload provided in Appendix 5 – Payload Example and a sample document that you download to your own file system named “Sample Document for Uploading.pdf”.

AppLink Generic Shared Test Credentials
You can request a set of unique test credentials, such as an api_key and payload, from a Nuvei Integration Analyst - or you can begin testing immediately using the generic 'Shared Test Credentials' provided within the API Documentation. To begin testing immediately, use test:Testing123$ as your api_key and use the test payload example provided in Appendix 5 - Payload Example.

Step 1: Open the Sandbox

Bring up the AppLink pre-production testing environment on the Innovation Center Sandbox Tools page:

https://developer.nuvei.com/applink-api/apis

You can also access the sandbox environment by selecting 'Sandbox Tools' then 'AppLink' from Innovation Center Main Menu:

 

 

Step 2: Utilize the POST USApplication_CreateApplication (United States Application)

Click on the USApplication_CreateApplication hyperlink in the presented screen as shown below:

 

 

Step 3: Log into the Sandbox

Select "HTTP Basic" to set Authentication. Enter the “Shared Test” api-key, test:Testing123$, as shown below:

Enter the “Shared Test” api-key, test:Testing123$, as shown below. Then click the “Save” button to return to the sandbox.

 

Step 4: Entering the Payload

The POST operation /Application/US is used to send a “JSON" formatted payload with all of the Merchant Application’s data.

 

Step 4.1: Paste the Payload provided in Appendix 5 - Payload Example within the Request Body section of /Application/US and then click 'Send This Request'.

 

 

Step 5: Get The ApplicationId

Clicking “Send This Request” sends the payload data to the API. The top of the page may display "Working..." for several seconds during this process.

If an invalid api_key was entered, you will get INVALID CREDENTIALS with a response code 401.

Otherwise the API returns the unique identifier, the ApplicationId, for the Merchant Application payload that was submitted. The Sandbox will show the CURL used to execute the API along with the response information including the Response Body.

As shown in the response screen example below, the Response Body provides the ApplicationId marked below. Make sure to copy down the ApplicationId as it will be needed in future steps.

Note: CURL is a command line tool that can be used in UNIX for getting or sending files using URL syntax.

 

 

Step 6: Load Documents related to the Merchant Application

This step provides for uploading the required merchant documentation like the merchant application form or a void check. The ApplicationId, generated above, is used to associate the documents to the payload. 

 

Step 6.1:  Utilize the POST USApplication_CreateDocument (United States Application)

Return to the AppLink Sandbox Tools page. Click on the USApplication_CreateDocument hyperlink in the presented screen as shown below:

 

Step 6.2: The following screen appears. In the Resource URL section, paste the ApplicationId generated from USApplication_CreateApplication in the {id} area as shown from 'Arrow A'.

 

Step 6.3: In the Query Parameters section, define the document type that best describes what is being attached, based upon the selection listed below:

  • ApplicationAndAgreement
  • ProcessingStatements
  • ProofOfBusiness
  • VoidCheck
  • EquipmentForm
  • NonProfitEvidence
  • Other

For our example enter “Other” as the 'DocumentType' as shown from 'Arrow B'.

Step 6.4: Click the “Choose File” button from 'Arrow C' to locate and add the digital file that represents the document from your local file system. Digital file types accepted are:

  • XML
  • PDF
  • JPG
  • PNG
  • TIFF
  • TXT
  • DOC
  • DOCX
  • ZIP
  • JPEG
  • WAV

 

Any other file extension will cause the API to respond with a 401 Fail response.

For our example use the file “Sample Document for Uploading.pdf” that you downloaded into your local file system and select it using CHOOSE FILE approach.

Only one document file can be uploaded at a time but this operation can be repeated as many times as needed to provide all the supporting documents required.

 

Step 6.5: Click the “Send This Request” button as shown from 'Arrow D' to upload the supporting document. A response code of 204 indicates the document upload is successful.

 

 

Step 7: Submitting the Merchant Application

This step validates the payload information then submits the merchant’s application to our onboarding system. If you utilized the Shared Test payload and provided file this operation should be a success.

 

Step 7.1:  Utilize the POST USApplication_SubmitApplicationSync (United States Application)

Return to the AppLink Sandbox Tools page. Click on the USApplication_SubmitApplicationSync hyperlink in the presented screen as shown below:

 

Step 7.2: The following screen appears. In the Resource URL section, paste the ApplicationId generated from USApplication_CreateApplication in the {id} area:

 

Step 7.3: Click the “Send This Request” button.

A response code of 200 indicates the Merchant Application was successfully submitted.

This Sandbox example shows you how the AppLink Web API is used to submit Merchant Application “payload” data and supporting documentation. This is an example of what your application will be reqiured to do to work with AppLink API.

Note
You can utilize the Sandbox with your api_key and “payload” that you received by following the instructions in the section “Get your testing credentials (api_key)” as a quick test. Follow the same steps as above just substitute your api_key, payload and document into the steps.

Need Help?

How can we help you today?  Our team is standing by and just a click away.