Onboarding APIs
Version
Current Specification Version: V8.2.2
Supported Operations
General Information
The purpose of this document is to provide documentation for 3rd parties to integrate with TidyPay processing gateway for using onboarding API. This API allows an integrator to use a special application to onboard the merchants. The onboarding application is a set of forms designed for obtaining a merchant account within the gateway. Within the application, a merchant will use the pages that will look similar to the following ones:
The connection URL for the sandbox server is: https://[server-name]/gates/onboarding.
Authorization is done via service users. To access the API, a service user is required to be granted with a corresponding privilege. A user can submit API requests using either associated credentials or temporary password generated via authentication operation.
When submitting an API request, you can use either TidyPay server URL or the Sanitizing Data Filter (Unibroker) server URL as an endpoint.
Requests that contain tokenized card numbers/bank account numbers can be submitted directly to {Unipay} server.
To reduce PCI exposure, requests with non-tokenized (raw) account data should be passed through the sanitizing data filter server. Otherwise, L04 error will be returned (Processing of raw account data is not allowed through the specified API end-point for the current user).
If you don’t have a specific reason, we recommend sending all the requests to the same endpoint (data filter).
To learn more about service users and end-points used for API submission, review Security Management guide.
Request method must be POST. For convenience purposes, sandbox server accommodates GET request as well. However, in production environment only POST request is allowed.
The content-type must be set to application/x-www-form-urlencoded when POST request is used.
Request fields are passed as HTTPS request parameters (including cases with callbacks) using name1=key1&name2=key2 (GET URL) format.
Response fields are passed within the body part of the HTTPS response as a part of the redirect to the response onboarding page.
Authorization is done via service users. To access the API, a service user is required to be granted with a corresponding privilege. A user can submit API requests using either associated credentials or temporary password generated via authentication operation.
When submitting an API request, you can use either TidyPay server URL or the Sanitizing Data Filter (Unibroker) server URL as an endpoint.
Requests that contain tokenized card numbers/bank account numbers can be submitted directly to {Unipay} server.
To reduce PCI exposure, requests with non-tokenized (raw) account data should be passed through the sanitizing data filter server. Otherwise, L04 error will be returned (Processing of raw account data is not allowed through the specified API end-point for the current user).
If you don’t have a specific reason, we recommend sending all the requests to the same endpoint (data filter).
To learn more about service users and end-points used for API submission, review Security Management guide.
Request method must be POST. For convenience purposes, sandbox server accommodates GET request as well. However, in production environment only POST request is allowed.
The content-type must be set to application/x-www-form-urlencoded when POST request is used.
Request fields are passed as HTTPS request parameters (including cases with callbacks) using name1=key1&name2=key2 (GET URL) format.
Response fields are passed within the body part of the HTTPS response as a part of the redirect to the response onboarding page.
Supported Operations
The operation used to onboard a new merchant.
The operation used to onboard a new affiliate.
Callback issued to the URL supplied by a submitter for delivering of onboarding process result.
The operation used to retrieve a status of the onboarding application. Starting with the 7.2 release, this operation is renamed to Status.
The operation used to add an owner to the onboarding application that has been created but not submitted yet.
Note: If the onboarding application has been already submitted to a processor, the information will not be passed to the processor.
The operation used to deactivate an owner within the gateway.
Note: You cannot delete an owner that is a controlling officer.
The operation used to update and resubmit the information associated with an onboarded merchant before the application has been submitted or upon submission if it has not been approved by a processor.
To update the information associated with a successfully onboarded merchant, Update operation is used.
To update the information associated with a successfully onboarded merchant, Update operation is used.
The operation used to update the information associated with a merchant that has already been successfully onboarded. As a result, a new onboarding application is submitted to a processor.
For a merchant that has not been onboarded yet, the information can be resubmitted using Adjust operation.
For a merchant that has not been onboarded yet, the information can be resubmitted using Adjust operation.
Note: The information can be updated on a processor's side only if the processor supports this operation.
The operation used to activate/deactivate the terminal related to the onboarded merchant.
The operation used to load a merchant's data.
Message Formats
Usage:
| R | - | required in request/always present in response for direct debit transactions and credit card transactions of all levels (I, II, III). |
| O | - | optional in request/not always present in response. |
| C | - | conditional; conditions of the usage are defined below the corresponding section. |
| E | - | echo back from request; if present in request, it is present in response, if it is not present in request, it is not present in response. |
| R2 | - | required in request/always present in response for credit card transactions of level II and III only; optional for direct debit and level I credit card transactions. |
| R3 | - | required in request/always present in response for credit card transactions of III only; optional for direct debit and level I, II credit card transactions. |
| SR | - | required in request/always present in response for split transactions only. |
| I | - | for internal use only. |
| N | - | not used. |
| * | - | required fields in these specific sections are only required if this specific feature is used. |
Copyright ©
TidyPay. All Rights Reserved.
All Logos and Trademarks used or mentioned on this page are copyrighted property of their respective owners and are used for display purposes only.