Chapter 5 - Available Operation sin the AppLink Web API

Each of the AppLink Web API operations provides a specific function needed within the overall process of Merchant Application submission. The screen shot below shows the available operations:

Each operation is described in detail below along with an example.

GET /Application/US/List

Description:

This GET operation returns a list of Merchant Applications in the system based upon the parameters provided. Caution should be used on the range of dates supplied as a long running query and large results can be unintentionally generated.

Parameters:

Name

Required

Description

Format

Example

startDate

Yes

The filter beginning date

YYYY-MM-DD

2017-08-01  

endDate

Yes

The filter ending date

YYYY-MM-DD

2017-09-26

agentName

 

Select only this agent’s name

TEXT

RalphOscar

status

 

Select only applications with this status.

TEXT

Allowed Values:

New: An application that has been newly created

OutstandingElecSign: An application that has been submitted for electronic signature by the merchant. At this stage, the merchant has not signed the application yet. Electronic signatures are not available through the API; however, for partners that use both the UI and the API, applications entered through the UI will appear in the API, and vice versa.

CompleteElecSign: An application that has been signed by the merchant and is ready to be reviewed and submitted for boarding

Submitted: An application that has been submitted for boarding

Canceled: An application that has been cancelled by the sales agent. Cancelling applications is not available through the API.           

PendingMerchantReviewLink: An application that has been submitted to be reviewed and partially completed by the merchant. This functionality is not available through the API.

MerchantCompletedReviewLink: An application for which the merchant has completed Merchant Review.

OutstandingUnderwriting: An application that has been submitted for underwriting by an external service and is pending its response prior to being submitted.

startIndex

 

Page number to start on

Integer

5

pageSize

 

Number of records to return on a page

Integer

25

 

Example:
/Application/US/List?startDate=2017-08-01&endDate=2017-09-26

Response Content:
Success or failure based upon the response code returned. 

A successful response includes a JSON file listing the Merchant Applications based upon the parameters supplied. An example of a single application returned is shown below:

JSON
[ { "ApplicationId": "45358060-7336-4c76-ad5e-ecc8c028a966", "DbaName": "AppLink API Test US", "CountryCode": "US", "OrganizationId": null, "User": "test", "Status": "New", "SignatureStatus": null, "AgentRole": "Test Agent (Primary Agent)", "Agent": "Test Company", "Office": "Test Agent US", "Created": "2017-07-03T15:59:17.29", "CreatedBy": "test", "Updated": "2017-07-03T15:59:17.29", "UpdatedBy": "test" },

DELETE /Application/US/{id}

Description: 
This DELETE operation deletes the Merchant Application data from the system based upon the unique Application ID provided. The delete includes the “payload” data and any associated documents.

Parameters:

Name

Required

Description

Format

Example

Application ID

Yes

The unique Application ID to delete

Unique ID

02abc16-fdf7-406e-8c60-b514Bde23d84

 

Example:
/Application/US/02abc16-fdf7-406e-8c60-b514Bde23d84

Response:
Success or failure based upon the response code returned.
NOTE: This operation cannot be undone.

GET /Application/US/{id}

Description: 
This GET operation returns the Merchant Application data “payload” in the system for the unique Application ID provided.

Parameters:

Name

Required

Description

Format

Example

Application ID

Yes

The unique Application ID to retrieve

Unique ID

02abc16-fdf7-406e-8c60-b514Bde23d84

 

Example:
/Application/US/02abc16-fdf7-406e-8c60-b514Bde23d84

Response Content: 
Success or failure based upon the response code returned. 

A successful response includes a JSON file in your “payload” format. That file has the data stored for the unique Application ID.

PUT /Application/US/{id}.

Description: 
This PUT operation replaces the existing Merchant Application data “payload” in the system for the unique Application ID provided or if the unique Application ID does not exist and the createIfNew parameter is set to “true”, adds the Merchant Application data “payload” into the system for the unique Application ID.

Parameters:

Name

Required

Description

Format

Example

Application ID

Yes

The unique Application ID to overwrite the “payload”

Unique ID

02abc16-fdf7-406e-8c60-b514Bde23d84

“payload” file

Yes

The complete “payload” data file for this Application ID

JSON “Payload” layout

See appendix for an example

strict

 

Pre-validates the Merchant Application data using the same rules as the PreSubmitValidations operation

Text

true

createIfNew

 

If the unique Application ID does not exist, creates a Merchant Application for the unique Application ID

Text

true

 

Example:
/Application/US/02abc16-fdf7-406e-8c60-b514Bde23d84

Response: 
Success or failure based upon the response code returned. 

If strict is “true” and failure occurs then error information is provided. For example, if the JSON file contained "CorporateState": "ZZ", then an error code of 400 is returned and the Response Body contains:

JSON
{ "Message": "Error converting value \"ZZ\" to type 'PivotalPayments.App.AppLink.WebApi.Models.US.MerchantBusinessInformation_CorporateState'. Path 'MerchantBusinessInformation.CorporateState', line 10, position 38." }

POST /Application/US

Description: 
This POST operation adds the Merchant Application data “payload” into the system. 

Parameters:

Name

Required

Description

Format

Example

“payload” file

Yes

The complete “payload” data file for this Application ID

JSON “Payload” layout

See appendix for an example

strict

 

Pre-validates the Merchant Application data using the same rules as the PreSubmitValidations operation

Text

true

 

Example:
/Application/US

Response Content: 
Success or failure based upon the response code returned. 

A successful response includes the unique Application ID that will be used to reference this application as shown below: 

If strict is “true” and failure occurs then error information is provided as shown in PUT /Application/US/{id}.

GET /Application/US/{id}/ValidationChecks

Description: 
This function is obsolete and should not be used – DO NOT USE.

GET /Application/US/{id}/PreSubmitValidations

Description: 
This GET operation performs all the validation rules on the fields for the Merchant Application data “payload”. If validation errors occur the response contains the information needed for correction.

Parameters:

Name

Required

Description

Format

Example

Application ID

Yes

The unique Application ID to be validated

Unique ID

02abc16-fdf7-406e-8c60-b514Bde23d84

resubmit

 

DO NOT USE – internal Nuvei use only

 

 

Example:
/Application/US/02abc16-fdf7-406e-8c60-b514Bde23d84/ PreSubmitValidations

Response Content: 
Success or failure based upon the response code returned. 

A successful response is a 204 and nothing is returned

A failure response is a 400 and error information is provided as shown in PUT /Application/US/{id}.

POST /Application/US/{id}/Submit

Description: 
This POST operation first validates the Merchant Application data “payload”, just like the PreSubmitValidations operation, for the unique Application ID.  If there are no validation errors, the Merchant’s Application data “payload” and documents are sent to our onboarding system. 

 

Note:
This operation is considered to be synchronous as the operation waits until a success or failure response occurs before the operation is complete. This operation can take a considerable amount of time and you should carefully consider the use in your application design. The SubmitAsync operation should be considered instead, if your application design can be structured to avoid waiting for a response.

Parameters:

Name

Required

Description

Format

Example

Application ID

Yes

The unique Application ID to Submit

Unique ID

02abc16-fdf7-406e-8c60-b514Bde23d84

resubmit

 

DO NOT USE – internal Nuvei use only

 

 

 

Example:
/Application/US/02abc16-fdf7-406e-8c60-b514Bde23d84/Submit

Response Content:
 
Success or failure based upon the response code returned.

A failure response provides error information as shown in PUT /Application/US/{id}.

POST /Application/US/{id}/SubmitAsync

Description: 
This POST operation, based upon the unique Application ID, schedules the Merchant Application data “payload” to be validated and if there are no validation errors, the Merchant’s Application data “payload” and documents are sent to our onboarding system. 

This Asynchronous scheduling operation does not wait for the success or failure response. The response for this operation is returned to the URL provided in the requestCallback parameter. 

Parameters:

Name

Required

Description

Format

Example

Application ID

Yes

The unique Application ID to Submit

Unique ID

02abc16-fdf7-406e-8c60-b514Bde23d84

requestCallback

Yes

The URL where the response will be sent once the operation completes

URL

https://www.mycompany/applink/response

resubmit

 

DO NOT USE – internal Nuvei use only

 

 

Example:
/Application/US/02abc16-fdf7-406e-8c60-b514Bde23d84/ SubmitAsync?requestCallback=https://www.mycompany/applink/response
 
Response Content:
 
Success or failure based upon the response code returned.
 
A failure response provides error information to the Callback as shown in PUT /Application/US/{id}.

POST /Application/US/{id}/Document

Description: 
This POST operation uploads a supporting document for the Merchant Application identified by the unique Application ID. 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. 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. 
 
The file must be uploaded in the multipart/form-data format with an attachment named “file”. For example:
 
JSON
POST /Application/US/ 9f11f1a4-01ac-4c1c-a3bf-8836ed97f4a9/Document?documentType=Other&api_key=<... API Key ...> HTTP/1.1 Cache-Control: no-cache User-Agent: PostmanRuntime/7.2.0 Accept: */* Host: applinkapi.service.preproduction.nuvei.com Accept-Encoding: gzip, deflate Content-Type: multipart/form-data; boundary=--------------------------472144426427217032865867 Content-Length: 7574 Connection: keep-alive   ----------------------------472144426427217032865867 Content-Disposition: form-data; name="file"; filename="image.png" Content-Type: image/png <... content here ... > ----------------------------472144426427217032865867--

Only one file can be uploaded in a single request. Most HTTP libraries and REST clients provide helper functions that help construct a multipart/form-data payload for a file to be uploaded.
Parameters:

Name

Required

Description

Format

Example

Application ID

Yes

The unique Application ID for the Merchant Application that this document is to be attached to.

Unique ID

02abc16-fdf7-406e-8c60-b514Bde23d84

documentType

 

Yes

One of the Allowed Values listed that best describes the document being uploaded

Text

 

ALLOWED VALUES

ApplicationAndAgreement

ProcessingStatements

ProofOfBusiness

VoidCheck

EquipmentForm

Other

NonProfitEvidence

 

file

Yes

The full path for the file that will be upload

File Title

C:/my/app/viodcheck.pdf

Example:
See above. 

Response:
Success or failure based upon the response code returned.

DELETE /Application/US/{id}/Document/{name}

Description: 
This DELETE operation deletes the named supporting document for the Merchant Application identified by the unique Application ID. 

Parameters:

Name

Required

Description

Format

Example

Application ID

Yes

The unique Application ID for the Merchant Application that the document is part of

Unique ID

02abc16-fdf7-406e-8c60-b514Bde23d84

name

 

 

The name of the document to be deleted. This is the filename provided in the Content-Disposition in multipart/form-data – filename="image.png"

 

Text

image.png

Example:
/Application/US/02abc16-fdf7-406e-8c60-b514Bde23d84/Document/image.png

Response:
Success or failure based upon the response code returned.

 

NOTE:
This operation cannot be undone.

GET /Application/US/{id}/Documents

Description: 
This GET operation returns a list of the supporting documents related to the Merchant Application identified by the unique Application ID. 

Parameters:

Name

Required

Description

Format

Example

Application ID

Yes

The unique Application ID to get a list of attached documents

Unique ID

02abc16-fdf7-406e-8c60-b514Bde23d84

Example:
/Application/US/02abc16-fdf7-406e-8c60-b514Bde23d84/ Documents}

Response Content:
Success or failure based upon the response code returned. 

A successful response includes a JSON file of documents related to the Merchant Application in the format shown below:

JSON
[ { "FileName": "Other_1.pdf", "DocumentTypes": [ "Other" ], "Created": "2018-08-31T13:17:51.937", "CreatedBy": "test" } ]

Need Help?

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