Creating an Instant Payout
Access Endpoint URL: https://rest.everyware.com/api/payouts [POST]
You can use the CreatePayout method to generate an instant payout record to be sent via SMS text to a payee's specified (and validated) mobile number.
Contacts Must Be Created
Note: A valid contact will be created when the Create Payout API is used. You can also create a contact with the Create Customer API or Create Invoice API.
Date of Birth Validation
Currently, Date of Birth (DOB) is the key variable available for contact verification. A Payee will have five attempts to verify their identity with their DOB before the instant payout record is placed into hold status, requiring manual review.
FIFO methodology
Everyware applies a First-In, First-Out approach to sending instant payout text messages based on the order in which records are ingested. You may provide an optional, scheduled date in the future according to your timing requirements.
Inbound Parameters
Parameters should be passed in a single JSON-body object.
Parameter Name | Description | Optional/Required |
---|---|---|
PayoutBatchId | Alphanumeric identifier for the payout batch. | Optional for a single payout. Required for any payouts intended for a single batch. |
PayoutBatchName | Name of the Payout Batch. Defaults to "[DateAdded YYYY/MM/DD] Payout Batch" if left blank. Everyware will populate with a default batch name if missing. Not applicable for single payout. | Optional |
ExternalPayoutId | 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/payee | Required |
LastName | Last name of customer/payee | Required |
PhoneNumber1 | Main phone number of customer/payout recipient provided in 10-digit format. Must be valid mobile number or transaction will be declined. Example: 3055551212 | Required |
PhoneNumber2 | Additional phone number of customer/payout recipient provided in 10-digit format. Example: 3055551212 | Optional |
Email address of customer/payee | Optional | |
Address | Address of customer/payee | Optional |
City | City of customer/payee | Optional |
StateCode | State code of customer/payee | Optional |
ZipCode | Zip code of customer/payee | Optional |
ValidationId | Unique identifier that the customer/payee must match to pass the security check step required to accept their payout. Examples: DOB/PatientID/ CustomerID/MemberID | Required |
ValidationIdType | This required type will be utilized for the customer to validate on the Payout Payment form. Value will be "date", "numeric", or "text". | Required |
ValidationIdDescription | Description of required unique identifier. This will populate on the Payout Payment Receipt. | Required |
ValidationId2 | Second optional unique identifier that the customer must match to pass the security check step required to accept their payout. Example: DOB/ PatientID/ CustomerID/ MemberID | Optional |
ValidationId2Type | This 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. Value will be "date", "numeric" or "text". | Optional |
ValidationId2Description | Description of second unique identifier. This will populate on the Payout Payment Receipt. Example: Date of Birth | Optional |
PayoutAmount | Amount to be paid to customer/payee. | Required |
PayoutShortDescription | Short description that can be used to further describe the payout (25 characters max). Example: "Dentistry Overpayment" | Optional |
PayoutScheduleDateMin | 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. Note, some payout links may not send on their intended schedule date depending on security and payout account threshold settings. If left blank, the default is set to tomorrow's date. Example: Setting a payout so that it does not send before 7/12/2023. | Optional |
PayoutScheduleDateMax | Merchant may specify the latest date for the payout to be sent to the customer/payee, after which the customer/payee will have the number of days specified in the Payout Link Expiration field to complete the payout. Merchant may specify a required date that the payout must be sent. Format: mm/dd/yyyy | Optional |
PayoutLinkExpiration | Number of calendar days that the payout link is available from the date the payout was sent to the customer/payee. | Optional |
Metadata | Utilized for Merchant Reporting. Uses JSON format. | Optional |
MessageTextInitial | The initial message text received by a customer/payee to get a payout. Everyware can provide a default template. | Optional |
MessageTextReminder | The message text received by a customer/payee as a reminder to get a payout. Everyware can provide a default template. | Optional |
Code Sample
{
"payoutBatchId": "a24e0357-df47-44f5-b31c-730576bcf476",
"externalPayoutId": "ExternalPayoutId",
"clientReference": "ClientReference-89f7c151-dc3d-4f19-9668-5fc3e7fa5ec1",
"firstName": "John",
"lastName": "Doe",
"phoneNumber1": "202-555-0172",
"email": "[email protected]",
"address": "Brazos str.",
"city": "Austin",
"stateCode": "TX",
"zipCode": "123456",
"validationId": "DOB",
"validationIdType": "date",
"validationIdDescription": "Enter your DOB to validate",
"payoutAmount": 1,
"payoutShortDescription": "Lorem ipsum",
"payoutScheduleDateMax": "05/23/2024",
"payoutLinkExpiration": 4
}
curl --location 'https://rest.everyware.com/api/payouts' \
--header 'Authorization: Basic [xxx]' \
--header 'Content-Type: application/json' \
--data-raw '{
"payoutBatchId": "a24e0357-df47-44f5-b31c-730576bcf476",
"externalPayoutId": "ExternalPayoutId",
"clientReference": "ClientReference-89f7c151-dc3d-4f19-9668-5fc3e7fa5ec1",
"firstName": "John",
"lastName": "Doe",
"phoneNumber1": "202-555-0172",
"email": "[email protected]",
"address": "Brazos str.",
"city": "Austin",
"stateCode": "TX",
"zipCode": "123456",
"validationId": "DOB",
"validationIdType": "date",
"validationIdDescription": "Enter your DOB to validate",
"payoutAmount": 1,
"payoutShortDescription": "Lorem ipsum",
"payoutScheduleDateMax": "05/23/2024",
"payoutLinkExpiration": 4
}
{
"Data": {
"CorrelationId": "a9da5784-192e-4f5c-8867-66840f92ef6c"
},
"IsSuccessful": true,
"Message": "The payout has been successfully received"
}
Updated 8 months ago