Provide customer information used to establish a branded & secure PCI-compliant plug in session.
The IngoPay API - Session Management method is designed for web developers who wish to integrate the IngoPay iFrame into their website or web / mobile application. A working knowledge of HTTP requests and server-to-server API calls is required and outside the scope of this documentation.
The Session Management API supports one method, Session_Management to interact with the system in order to stage a one time use session.
You will need to initialize a session in order to mount the IngoPay iFrame SDK. This API request establishes the session at Ingo needed for a client to do so and establishes the customer information used in the customer interaction processing.
You will need to register for a participant_id via your Integration contact and receive credentials in order to create a session needed to load the plugin. This is done during the onboarding process with the Ingo Integrations Team.
Package Dependencies - There are no package dependencies to interact with this API. However, you will need to sign your requests with HMAC Authentication.
You will need to initialize a session in order to mount the Plugin SDK. This API request establishes the customer information required for generating a session at Ingo for use in the customer iFrame interactions, applicable verifications and tokenization processing.
The IngoPay API - Session Management Method supports one method to interact with the system in order to stage a single point-in-time time session. The IngoPay API - Session Management supports Idempotency for safely re-authorizing a session for continued logging of customer iFrame interactions and applicable verifications within the previously assigned session.
https://iip-session-management-uat.ingo.money/api/v1/sessions/point-in-time/plugin
HTTP: POST
Content Type: application/json
| PARAMETER | REQ’T | TYPE | LENGTH | DESCRIPTION |
|---|---|---|---|---|
| participant_unique_id1 | RQD | STR | 100 | Participant assigned ID for the verify request. This ID should be carried forward to the process request for tracking purposes. |
| participant_unique_id2 | OPT | STR | 100 | Optional second participant assigned ID for the verify request. This ID can also be carried forward to the process request for tracking purposes. |
| host_uri | OPT | STR | 200 | Optional parameter to specify the hosting application uri (should include protocol [https://] and host name --- e.g. https://digitalpay.ingo.money). Must be explicitly white-listed in client configuration (will receive Unauthorized if non-white listed uri specified). If not specified, will default to the 1st configured parent application host domain. |
| recipient_information | RQD | OBJ | The Client Provided Recipient Verification Information. | |
| first_name | RQD | STR | 150 | Recipient First Name |
| last_name | RQD | STR | 150 | Recipient Last Name |
| address_line1 | RQD | STR | 150 | Recipient Address Line 1 |
| address_line2 | OPT | STR | 150 | Recipient Address Line 2 |
| city | RQD | STR | 150 | Recipient City |
| state | RQD | STR | 2 | Recipient State. Must be a valid US state |
| zip_code | RQD | STR | 10 | Recipient Zip Code (ie: xxxxx or xxxxx-xxxx) |
| email_address | COND | STR | 150 | Recipient Email Address. Required for PayPal enabled participants |
| phone_number | OPT | STR | 10 | Recipient Phone Number. Numbers only |
| mobile_number | OPT | STR | 10 | Recipient Mobile Number. Numbers only. |
{
"participant_unique_id1": "ABC-1234-123545663",
"participant_unique_id2": "DEF-5678",
"host_uri": "https://digitalpay.ingo.money",
"recipient_information": {
"first_name": "Jack",
"last_name": "Frost",
"address_line1": "123 Main St",
"address_line2": "",
"city": "Atlanta",
"state": "GA",
"zip_code": "30313",
"email_address": "[email protected]",
"phone_number": "1231231234",
"mobile_number": "1231231234"
}
}
| PARAMETER | TYPE | DESCRIPTION |
|---|---|---|
| status | INT | Numeric code describing status of API request (e.g. 100 = Success). |
| client_message | STR | Text description associated with status code. |
| data | OBJ | Information about identifiers associated with the session request |
| session_identifier | STR | Unique identifier of the session |
| authorized_url | STR | Authorized URL. Should be utilized within 30 seconds of creation. |
| authorized_url_expiration_utc | DATE | Authorized URL expiration in UTC |
| participant_unique_id1 | STR | Transaction correlation ID |
| participant_unique_id2 | STR | Customer correlation ID |
| time | DEC | Time in seconds to complete the request |
{
"status": 100,
"client_message": "Success",
"data": {
"session_identifier": "7830227a-ba47-4d28-9416-cad41a446db7",
"authorized_url": "https://iip-webplugin-ingo.money/session/7830227a-ba47-4d28-9416-cad41a446db7?t=637126733246949906&h=rpSb%2f%2fAeOAKjX7%2fhhOQvj9zpvwf4xeg97TuPCMtpUg0%3d",
"authorized_url_expiration_utc": "2019-12-10T20:14:19.763941Z",
"participant_unique_id1": "1f271ff6-5b79-45b6-a71e-aa9d1b86c0d8",
"participant_unique_id2": ""
},
"time": 0.8
}
| PARAMETER | TYPE | DESCRIPTION |
|---|---|---|
| status | INT | Numeric code describing status of API request (e.g. 13400 = Field Validation Error). |
| client_message | STR | Text description associated with status code. |
| developer_message | STR | Optional developer message |
| data | OBJ | Information about error identifiers associated with the session request |
| time | DEC | Response time in seconds |
{
"status": 13400,
"client_message": "Field validation error - See data element for validation error details",
"developer_message": "invalid_request_fields",
"data": {
"participant_unique_id1": [
"The ParticipantUniqueId1 field is required."
]
},
"time": 0.0
}
The IngoPay API - Session Management Method supports Idempotency for safely retrying session initialization requests without accidentally performing the same operation twice, or creating a new transaction session - either due to network interference or a session termination event (e.g. Account Verification).
Note: As part of Ingo's product offering, clients have the ability to utilize our Recipient Verification and Account Verification Services. An attribute of these services enables clients to set a customer maximum attempt threshold by verification feature by session. In addition to individual thresholds, an overall session threshold may be established. Additional details on the configuration of Risk Management Services can be provided by your assigned Integration Solutions Manager.
| Code | Message | Applicable Call | Description |
|---|---|---|---|
| 101 | Success - Idempotent Response | Session | Returned when the Idempotency-Key value was processed successfully received on a prior request. A new session IS NOT created. A new authorized URL |
To perform an idempotent request, provide an additional Idempotency-Key header in your request. Idempotency works by saving the result of a successful IngoPay API - Session Management transaction along with session initialization activity data. Subsequent requests with the same idempotency key return the same transaction session. Idempotency keys are not saved for any failing Session Management API requests, and may be safely reused to generate a new session.
| KEY | VALUE | DESCRIPTION | MAX_LENGTH |
|---|---|---|---|
| Idempotency-Key | Request idempotency key | 250 |
An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. We recommend using V4 UUIDs, GUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys remain active in the system for 2 hours. New requests are generated if a key is reused after the original has expired and been pruned. The system compares incoming parameters to those of the original request, and will generate an error if they are not the same to prevent accidental misuse.
A few example scenarios have been provided below where utilizing idempotency could prove useful.
Example Scenario 1: If a request to initialize a transaction session does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one transaction session is created.
Example Scenario 2: In another instance, if a customer fails verification (e.g. Recipient Verification Data Matching) reaching the maximum attempts allowed, this would create a non-terminal event. You can retry the request with the same idempotency key to generate a new authorized url for the same session. The customer can then continue & re-attempt verification until the overall session maximum attempts counter is triggered, resulting in a terminal event.
{
"status": 101,
"client_message": "Success - Idempotent",
"data": {
"session_identifier": "5cf34a7d-25b6-4400-b19d-53a171d324e1",
"authorized_url": "https://iip-webplugin-uat.ingo.money/session/5cf34a7d-25b6-4400-b19d-53a171d324e1?t=737135937108347861&h=%2fHdR2ZYGoNDaqmyhUO1HmoWpJRa2zNjNtFXcJsuJJww%3d",
"authorized_url_expiration_utc": "2020-01-02T20:30:30.8347861Z",
"participant_unique_id1": "2639d2ce-2e74-48a4-be74-9bb90a62b40b",
"participant_unique_id2": ""
},
"time": 0
}
{
"status": 13723,
"client_message": "Idempotency Key <idempotency_key> for ParticipantId <participant_id> does not match the original request",
"developer_message": "invalid_idempotent_request",
"data": null,
"time": 0.0
}