Instant Payout Inquiry
Access Endpoint URL: https://rest.everyware.com/api/payouts/inquiry [POST]
The Instant Payout Inquiry returns the statuses, transfer method, and reason codes for statuses of any instant payout records - from ingested to completed, as described below.
Inbound Parameters
Parameters should be passed in a single JSON-body object.
| Parameter Name | Description | Optional/Required |
|---|---|---|
| BatchId | Alphanumeric identifier for the payout batch. Required for any payouts that are intended for a single batch. | Optional |
| ExternalId | Unique identifier Everyware can store with each individual payout. Data will populate the Payouts report if the records are successfully added. | Optional |
| ClientReference | An original payment transaction ID associated with the intended payout. Provided by merchant and may be used to acknowledge that the contact/customer is receiving a transfer for an amount previously paid outside of Everyware. Example: "Patient Payment for Invoice #2209" |
Optional |
| FirstName | First name of customer/payout recipient. | Optional |
| LastName | Last name of customer/payout recipient. | Optional |
| PhoneNumber1 | Main phone number of customer/payout recipient (10-digits max, no formatting). Must be a valid mobile number or the transaction will be declined. Example: 3055551212 |
Optional |
| PhoneNumber2 | Additional phone number of customer/payout recipient (10-digits max, no formatting). Example: 3055551212 |
Optional |
| CorrelationId | Unique Identifier for each payout | Optional |
Response Parameters
| Parameter Name | Description |
|---|---|
| CorrelationId | Unique Identifier of a payout |
| BatchId | Alphanumeric ID for the payout batch. Required for any payouts that are intended for a single batch. |
| BatchName | Name of the Payout Batch. Defaults to "[DateAdded YYYY/MM/DD] Payout Batch" if left blank. |
| ExternalId | Unique identifier Everyware can store with each individual payout. Data will populate the Payouts report if the records are successfully added. |
| ClientReference | An original payment transaction ID associated with the intended payout. Provided by merchant and may be used to acknowledge that the contact/customer is receiving a transfer for an amount previously paid outside of Everyware. Example: "Patient Payment for Invoice #2209" |
| FirstName | First name of Payout recipient |
| LastName | Last name of Payout recipient |
| PhoneNumber1 | Mobile phone number of customer, provided in 10 digit format: 3055551212. |
| PhoneNumber2 | Additional phone number of customer, provided in 10 digit format: 3055551212. |
| Email of Payout recipient | |
| Address | Address of Payout recipient |
| City | City of Payout recipient |
| StateCode | State code of Payout recipient |
| ZipCode | Zip code of Payout recipient |
| ValidationId | Unique identifier that the customer must match to pass the security check step required to accept their payout. E.g., date of birth |
| ValidationIdType | This required ID type will be utilized for the customer to validate on the Payout Payment form. It will change dynamically depending on the validation ID passed by the Merchant. Will be date, numeric or text. |
| ValidationIdDescription | Description of required unique identifier - for example, Date of Birth |
| ValidationId2 | Unique identifier that the customer must match to pass the security check step required to accept their payout. E.g., date of birth |
| ValidationId2Type | This required ID type will be utilized for the customer to validate on the Payout Payment form. It will change dynamically depending on the validation ID passed by the Merchant. Will be date, numeric or text. |
| ValidationId2Description | Description of required unique identifier - for example, Date of Birth |
| Amount | Amount to be paid to payout recipient |
| ShortDescription | Short description that can be used to further describe the payout. For example, you were issued a refund for "Dentistry Overpayment." 25 character max |
| ScheduleDateMin | The intended date for the payout link to be generated and sent by text message to the contact. This can also be used to schedule payouts in the future (do not send before 7/1/2024). If left blank, tomorrow's date is default. Format: mm/dd/yyyy Note, some payout links may not send on their intended schedule date depending on security and payout account threshold settings. |
| ScheduleDateMax | Merchant may specify a required date that the payout must be sent. This represents the last desired date that the payout text link to be offered to the consumer. The consumer will have until the Payout Link Expiration as defined below to complete the payout. Format: mm/dd/yyyy |
| LinkExpirationDays | Number of calendar days that the payout link is available from the date the payout was sent to the consumer. Default (max) is 7 days. |
| ScheduleDate Karmatic | Date that the payout has been scheduled through Payout scheduler. |
| SentDateTime | Date and time the text notification was actually sent to consumer |
| IsLinkValid | Defines is payout link is valid: If sentDateTime minus today is beyond linkExpirationDays (days in which payout link is available) payout link is no longer valid |
| LinkClickedTimes | The number of times the consumer has clicked the Payout link |
| Status | Status of the Payout. See payout status table below for more details. |
| ReasonCodeId | Field that can provide additional details for payout errors. See reason code table below for more details. |
| TransferMethod | Upon a successful payout completion, the system identifies whether the consumer selected Push to Card, Bank Account (RTP), or Bank Account (ACH). See transfer method table below for more details. |
| tTansferReference | Transaction reference code provided by Cross River Bank |
| IsCompletionConfirmed | Defines if a confirmation from CRB that the payout has been executed was received. Example - push to card may complete in 30 min |
| CompletionDateTime | Date and time that the consumer completed the payout |
| SettlementDateTime | Date and time that the payout was settled |
| Fee | Fee assessed for the completed processing of the payout. |
| Metadata | Custom properties in JSON format specified by merchant on payout creation |
Payout Status
| Value | Status | Description |
|---|---|---|
| 1 | Created | Registered in database - default when created |
| 2 | Scheduled | Scheduled to be sent |
| 3 | On hold | Flagged - for example, because of duplicate entry check or other AML check |
| 4 | Sent | Awaiting acceptance - payout link has been sent to payee |
| 5 | Completed | Payee successfully accepted payout |
| 6 | Failed | Payee has attempted 5 attempts to verify their identity |
| 7 | Abandoned | Payout link was sent and now has expired |
| 8 | Settled | Funds have settled with Payee's financial institution. |
| 9 | Rejected | |
| 10 | Refunded | |
| 11 | Canceled |
Transfer Methods
Payees will be presented with the option to have funds transferred to their debit card or bank account. Everyware will move funds according to Payee preference and their financial institution's capabilities. If a Payee selects a real time payment (RTP) transfer method but their financial institution does not support RTP technology, Everyware will revert to a same-day ACH payment approach. Payees are notified by text message when their payouts settle.
| Value | Method | Description |
|---|---|---|
| 0 | Push to Card | Funds pushed to payee's debit card |
| 1 | Bank Account | Funds transferred to payee's bank account as real-time-payment (RTP) |
| 2 | Bank Account | Funds transferred by Same-Day ACH |
Reason Codes
Coded reasons for when an Instant Payout is unsuccessful are provided as described below.
| Value | Reason | Description |
|---|---|---|
| 1001 | Contact info does not match | Payout customer found in system by phone number but first and last name do not match the ones specified in payout request. |
| 1002 | Transaction amount below min limit | Payout amount is less than transaction limit configured per merchant |
| 1003 | Transaction amount above max limit | Payout amount is more than transaction limit configured per merchant |
| 1004 | Duplicate check failed | A payout with the same phone number and amount is in system |
| 1005 | Payout account not created | Merchant does not yet have an established payout account with an Everyware Instant Payout banking partner. |
| 1006 | Payout account not activated | Merchant has a payout account at an Instant Payout financial institution but it has yet to be activated or connected to their Sales Site/Location in Everyware. |
| 1007 | Insufficient balance | Merchant's balance is insufficient to process a payout |
| 1008 | Daily limit for payouts exceeded | Unable to schedule a payout |
| 1009 | Monthly limit for payouts exceeded | Unable to schedule a payout |
| 1010 | Schedule date max is in past | |
| 1011 | Customer opted out of text messaging | Payee's mobile number to which you're trying to send the Instant Payout link has blocked messages from the merchant's assigned messaging number |
| 1019 | Flagged by AML check | Everyware has reviewed the instant payout record and has held back the payout link from sending to the Payee upon noticing a potential risk threat |
| 1100 | Validation attempts exceeded | The Payee has attempted to verify their identity by entering the wrong date of birth in their Instant Payout Security Check step. This likely means the DOB they're entering does not match that stored with their contact profile. |
| 1101 | Transaction canceled by merchant | Merchant has applied the cancel action to the Instant Payout record in question in the Everyware portal. |
| 1102 | Transaction rejected during processing | |
| 1103 | Transaction failed during processing | |
| 1104 | Transaction canceled during processing | |
| 1105 | Refund was requested | |
| 1106 | Research required | |
| 1107 | Transaction escalated | |
| 1108 | Manual override |
Code Sample
{
"batchId": "8ef23f5e-f423-42d5-be9e-41af8763b0f9",
"externalId": "f6d18621-10e9-4f1f-9547-44cf5f074477",
"clientReference": "997860dc-daff-40e7-af45-3033c41b2931",
"firstName": "John",
"lastName": "Doe",
"phoneNumber1": "205-222-2275",
"phoneNumber2": null,
"correlationId": "99192dcc-203d-44c4-a434-1d0cbd736461"
}
curl --location 'https://rest.everyware.com/api/payouts/inquiry' \
--header 'Authorization: Basic [xxx]' \
--header 'Content-Type: application/json' \
--data-raw ' {
"batchId": "8ef23f5e-f423-42d5-be9e-41af8763b0f9",
"externalId": "f6d18621-10e9-4f1f-9547-44cf5f074477",
"clientReference": "997860dc-daff-40e7-af45-3033c41b2931",
"firstName": "John",
"lastName": "Doe",
"phoneNumber1": "205-222-2275",
"correlationId": "99192dcc-203d-44c4-a434-1d0cbd736461"
}
{
"Data": [
{
"CorrelationId": "99192dcc-203d-44c4-a434-1d0cbd736461",
"BatchId": "8ef23f5e-f423-42d5-be9e-41af8763b0f9",
"BatchName": "2023/08/03 Payout Batch",
"ExternalId": "f6d18621-10e9-4f1f-9547-44cf5f074477",
"ClientReference": "997860dc-daff-40e7-af45-3033c41b2931",
"FirstName": "Jane",
"LastName": "Doe",
"PhoneNumber1": "2052222275",
"Email": "test3@everyware.com",
"Address": "Brazos str.",
"City": "Austin",
"StateCode": "TX",
"ZipCode": "123456",
"ValidationId": "DOB",
"ValidationIdType": 0,
"ValidationIdDescription": "Enter your DOB to validate",
"ValidationId2": null,
"ValidationId2Type": null,
"ValidationId2Description": null,
"Amount": 1.0000,
"ShortDescription": "Lorem ipsum",
"ScheduleDateMin": "2023-08-04T00:00:00",
"ScheduleDateMax": "2024-05-30T00:00:00",
"ScheduleDate": "2023-08-04T00:00:00",
"SentDateTime": "2023-08-03T20:47:10.983",
"LinkExpirationDays": 15,
"Metadata": null,
"CreatedAt": "2023-08-03T20:40:28.347",
"LinkClickedTimes": 0,
"Status": 4,
"ReasonCodeId": null,
"TransferMethod": null,
"TransferReference": null,
"IsCompletionConfirmed": false,
"CompletionDateTime": null,
"SettlementDateTime": null,
"Fee": null,
"IsLinkValid": true
}
],
"IsSuccessful": true,
"Message": null
}