The URL to send all of your MP PayFac responses to the Merchant Provisioner API Sandbox is the following:
NOTE: Requests made to the Sandbox environment require the connection be TLS 1.2
| Key | Value | Description |
|---|---|---|
| Authorization | Basic username:password |
Contains Base-64 encoded credentials in this format. |
| Content-Type | application/com.vantivcnp.payfac-v13+xml |
Version number depends on the API used. |
| Accept | application/com.vantivcnp.payfac-v13+xml |
Version number depends on the API used. |
E.g. username:password = merchant1:password
Base-64 encoded = Basic bWVyY2hhbnQxOnBhc3N3b3Jk=
NOTE: Sandbox does not validate the credential. It is recommended to use dummy values
for credential to be prepared for live environment.
Send a simple GET request to Sandbox using your HTTP tool. The following would be the curl command to submit the GET request:
Please check that you don't have a proxy setup. If you do have a proxy setup, here is the command to submit the previous XML with a Proxy.
The following HTTP request methods of the Merchant Provisioner PayFac API are supported in Sandbox.
NOTE: To see examples for each of the methods, click on the method name.
| Method | URI/Query | Description |
|---|---|---|
| POST | /legalentity/<legalEntityId>/agreement |
Request to designate the version of the agreement along with information about the agreeing party. |
| GET | /legalentity/<legalEntityId>/agreement |
Request to retrieve all agreements associated with a specified Legal Entity. |
| POST | /legalentity |
Request to create a new Legal Entity. |
| PUT | /legalentity/<legalEntityId> |
Request to update data associated with the designated Legal Entity. |
| GET | /legalentity/<legalEntityId> |
Request for information and/or status of the designated Legal Entity. |
| POST | /legalentity/<legalEntityId>/principal |
Request to create a new Principal associated with a Legal Entity. |
| DELETE | /legalentity/<legalEntityId>/principal/<principalId> |
Request to delete a Principal associated with a Legal Entity. |
| POST | /legalentity/<legalEntityId>/submerchant |
Request to create a Sub-merchant associated with the designated Legal Entity. |
| PUT | /legalentity/<legalEntityId>/submerchant/<subMerchantId> |
Request to update data associated with the designated Sub-merchant. |
| GET | /legalentity/<legalEntityId>/submerchant/<subMerchantId> |
Request to retrieve information about the designated Sub-merchant. |
| GET | /mcc |
Returns the list of merchant category codes that are currently approved for the Payment Service Provider. |
Almost all HTTP methods have a response Code and response Description attribute in their responses. For the
/legalentity POST, changing the last two digits of taxId in the request will
result in a different response code. However, for every other method, changing the last two digits of
the legalEntityId will result in a different response code. A list of all the possible
response Codes and their associated description is listed below.
| Type | Description |
|---|---|
| Response Codes |
10 - Approved 20 - Manual Review 30 - Retry 35 - Manual Review (Duplicate) 36 - Duplicate 40 - Declined 98 - Manual Review (End Point Down) 99 - Manual Review (Background Check Error) ** - Anything else results in code 10 and description Approved |
If the last three characters of the legalEntityId are one of the below,
a HTTP error code will be generated.
| Type | Description |
|---|---|
| HTTP Errors |
400 - Could not find requested object. 401 - You are not authorized to access this resource. Please check your credentials. 500 - Internal Error. This error has already been escalated to Vantiv for resolution. Please contact support with questions. 503 - Service was unavailable. |
There are two types of requests that can be sent in the HTTP POST method with URL /legalentity/<legalEntityId>/submerchant.
Merchant Name is set to duplicate all matching in the Request, Sandbox will return a Create SubMerchant Response
with submerchantId and merchantIdentString only.
Merchant Name is set to duplicate not matching in the Request, Sandbox will return a Create SubMerchant Response
with originalSubmerchant that has all information on SubMerchant.
In the /legalentity/<legalEntityId>/agreement POST method, if the create request sent is a
duplicate, the response message will include a duplicate="true" attribute at the end.
More specifically, if the last three digits of the legalEntityId are 000, the root element (in this case
legalEntityAgreementCreateResponse) will have the duplicate="true" attribute.
The purpose of the DELETE method is to delete the principal Id that is associated with the passed in legalEntityId. However, be sure that when testing the value that is passed for the PrincipalId is between 1-11 to ensure a successful test of the DELETE method.
To test the /mcc HTTP method send a GET request to the URL mentioned below.
The approvedMccResponse should look similar to below.
To test the /legalentity/<legalEntityId> HTTP method, send a GET request to the URL mentioned below.
The legalEntityRetrievalResponse should look similar to below.
NOTE: Change the last three characters of the legalEntityId to one of the below codes
to create that many Agreement Responses.
| Type | Description |
|---|---|
| Agreement Responses |
000 - No Agreements 001 - One Agreement 002 - Two Agreements 003 - Three Agreements 004 - Four Agreements 005 - Five Agreements 006 - Six Agreements 007 - Seven Agreements 008 - Eight Agreements 009 - Nine Agreements * * * - Any other code (except HTTP errors) contains One Agreement |
To test the Agreement information above send a HTTP GET request to the URL mentioned below.
This request has a legalEntityId of 201003. Therefore, the response should have three
legalEntityAgreement as aforementioned.
The legalEntityAgreementRetrievalResponse should look similar to this.
To test the /legalentity/<legalEntityId>/submerchant/<subMerchantId> HTTP method, send a GET
request to the URL mentioned below.
The subMerchantRetrievalResponse should look similar to below.
A legalEntityUpdateRequest can be sent to the Sandbox to receive a legalEntityResponse
that contains a random legalIdentityId of max Length 19 characters.
To test the /legalentity/<legalEntityId> HTTP method, use the following URL.
An example of a legalEntityUpdateRequest is below.
Using the URL and request above, the Sandbox should respond with a legalEntityResponse
similar to the one below.
To test the /legalentity/<legalEntityId>/submerchant/<subMerchantId> HTTP method, send a PUT request
to the URL mentioned below.
Use the request below (or something similar) to receive the response for this PUT method.
The response should similar to below.
To test the /legalentity HTTP method, send a POST request to the URL mentioned below.
Use a request that is similar to below to generate the response.
The legalEntityCreateResponse should look similar to below.
To test the /legalentity/<legalEntityId>/agreement HTTP method, send a POST request to the URL
mentioned below.
Use a request that is similar to below to generate the response for the POST method.
The legalEntityAgreementCreateResponse should look similar to below.
To test the Agreement duplicate attribute, send a POST request to the URL above changing the last three digits of the legalEntityId to 000. The response should look similar to the one below.
To test the /legalentity/<legalEntityId>/principal HTTP method, send a POST request to the URL mentioned below.
Use the request below to generate a response for the POST method.
The principalCreateResponse should look similar to below.
The URL for the SubMerchant request is below
Below is a basic request for the SubMerchant POST method.
Using the request above, the Sandbox will send the response below if Merchant Name
is set to duplicate all matching.
Similarly, the Sandbox will send a response similar to below if Merchant Name is
set to duplicate not matching.
To test the /legalentity/<legalEntityId>/principal/<principalId> HTTP method, send a DELETE
request to the URL mentioned below.
The principalDeleteResponse should look similar to below.
Postman samples for the above requests can be downloaded from here.