Chapter 5 - Available Operations in the AppLink Web API link
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:
Section 5.1 - GET /Application/CA/List link
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/CA/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:
[
{
"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"
},
Section 5.2 - DELETE /Application/CA/{id} link
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/CA/02abc16-fdf7-406e-8c60-b514Bde23d84
Response:
Success or failure based upon the response code returned. NOTE: This operation cannot be undone.
Section 5.3 - GET /Application/CA/{id} link
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/CA/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.
Section 5.4 - PUT /Application/CA/{id}. link
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/CA/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:
Section 5.5 - POST /Application/CA link
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/CA
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/CA/{id}.
Section 5.6 - GET /Application/CA/{id}/ValidationChecks link
Description:
This function is NOT AVAILABLE in the Canadian version of the API – DO NOT USE.
Section 5.7 - GET /Application/CA/{id}/PreSubmitValidations link
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 |
|
|
Example:
/Application/CA/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/CA/{id}.
Section 5.8 - POST /Application/CA/{id}/Submit link
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 |
|
|
Example:
/Application/CA/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/CA/{id}.
Section 5.9 - POST /Application/CA/{id}/SubmitAsync link
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 |
|
|
Example:
/Application/CA/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/CA/{id}.
Section 5.10 - POST /Application/CA/{id}/Document link
Description:
This POST operation uploads a supporting document for the Merchant Application identified by the unique Application ID. Digital file types accepted are:
- XML
- 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:
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: https://applink.service.preproduction.nuvei.com/applinkapi.service.preproduction.pivotalpayments.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.
Section 5.11 - DELETE /Application/CA/{id}/Document/{name} link
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/CA/02abc16-fdf7-406e-8c60-b514Bde23d84/Document/image.png
Response:
Success or failure based upon the response code returned. NOTE: This operation cannot be undone.
Section 5.12 - GET /Application/CA/{id}/Documents link
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/CA/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: