Payout Links

A Payout Link is a unique, one-time link you can send via email or text to a recipient for fast and secure payouts. For card-based payouts, funds are typically available within minutes.

Payout Links can be used for various purposes, including insurance payments, sales commissions, and more. Each link can be customized to display your brand name and logo, providing a seamless experience for recipients.

Payout Links

Create a Payout Link

Generate a Payout Link resource to create a single-use link for sending a payout to a recipient.

Request

header Parameters

Finix-Version

string

Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01

Request Body schema: application/json

	object Object containing additional details about the `Payout Link`.
allowed_payout_operations required	Array of strings Defines the types of operations permitted in the payout process when the recipient submits the payout form. Acceptable values include: PUSH_TO_ACH PUSH_TO_CARD
required	object Contains information about the amount paid to the recipient through the `Payout Link`.
	object Object containing branding details for the `Payout Link`.
items required	Array of arrays Default: [] The list of items that will be "paid out". For example, insurance payouts, sales commissions, etc.
nickname	string A human-readable name for the resource.
	object or null Details of the recipient.
	object or null Include up to 50 `key: value` pairs to annotate requests with custom metadata. Maximum character length for individual `keys` is 40. Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)

Responses

201

Response schema for creating a Payout Link.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

422

Invalid field

post/payout_links

Request samples

curl

curl -i -X POST \
  -u US9bhCUqoTxo7V6di8ceb3Td:e704591a-1972-4b41-9884-6a67f5d7cdbb \
  https://finix.sandbox-payments-api.com/payout_links \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "allowed_payout_operations": [
      "PUSH_TO_CARD"
    ],
    "nickname": "Insurance Claim #2552",
    "tags": {
      "collectEmail": false,
      "collectPhoneNumber": false
    },
    "items": [
      {
        "name": "Insurance Payout #2552",
        "description": "Car Damage",
        "quantity": "1",
        "image_details": {
          "primary_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/8/88/Uninsured_cars_seized_by_police_in_Liverpool.JPG/220px-Uninsured_cars_seized_by_police_in_Liverpool.JPG"
        },
        "price_details": {
          "amount": 100000,
          "currency": "USD"
        }
      }
    ],
    "amount_details": {
      "total_amount": 100000,
      "currency": "USD"
    },
    "additional_details": {
      "expiration_in_minutes": 10080,
      "terms_of_service_url": "https://example.com/terms"
    },
    "branding": {
      "icon": "",
      "brand_color": "#0D121A",
      "accent_color": "#0B5DBC",
      "button_font_color": "#FFFFFF",
      "logo": "https://s3-us-west-2.amazonaws.com/payments-dashboard-assets/dashboard.finixpayments.com/2022-04-28-22_56_33-finix-logo-v2.png"
    },
    "recipient_details": {
      "first_name": null,
      "last_name": null,
      "business_name": null,
      "doing_business_as": null,
      "email": null
    }
  }'

Response samples

application/json

{"id": "payout_link_ches9gZg2WWM7ARM53pmP",
"additional_details": {"success_return_url": null,
"unsuccessful_return_url": null,
"expired_session_url": null,
"terms_of_service_url": "https://example.com/terms",
"expiration_in_minutes": 10080
},
"allowed_payout_operations": ["PUSH_TO_CARD"
],
"amount_details": {"total_amount": 100000,
"currency": "USD"
},
"application_id": "AP5Tq3MMxKwHYX7soDncrCQ3",
"branding": {"brand_color": "#0D121A",
"accent_color": "#0B5DBC",
"logo": "https://s3-us-west-2.amazonaws.com/payments-dashboard-assets/dashboard.finixpayments.com/2022-04-28-22_56_33-finix-logo-v2.png",
"icon": "",
"logo_alternative_text": null,
"button_font_color": "#FFFFFF"
},
"created_at": "2024-11-15T10:07:50.353254Z",
"items": [{"name": "Insurance Payout #2552",
"image_details": {"primary_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/8/88/Uninsured_cars_seized_by_police_in_Liverpool.JPG/220px-Uninsured_cars_seized_by_police_in_Liverpool.JPG",
"alternative_image_urls": [ ]
},
"price_details": {"amount": 100000,
"currency": "USD"
},
"description": "Car Damage",
"quantity": 1
}
],
"link_expires_at": "2024-11-22T10:07:50.335572Z",
"link_url": "https://link.sandbox-payments-checkout.com/Xjts64",
"nickname": "Insurance Claim #2552",
"recipient_details": null,
"state": "ACTIVE",
"tags": {"collectPhoneNumber": false,
"collectEmail": false
},
"updated_at": "2024-11-15T10:07:50.596865Z",
"_links": {"self": {"href": "https://finix.sandbox-payments-api.com/payout_links/payout_link_ches9gZg2WWM7ARM53pmP"
}
}
}

List Payout Links

Retrieve a list of Payout Link resources.

For details on how to query endpoints using the available parameters, see Query Parameters.

Request

query Parameters

limit	integer The numbers of items to return. Example: limit=10
after_cursor	string Return every resource created after the cursor value. Example: after_cursor=TRnasXQ5AmjsLnPMwnme7TL4
before_cursor	string Return every resource created before the cursor value. Example: before_cursor=TRnasXQ5AmjsLnPMwnme7TL4

header Parameters

Finix-Version

string

Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01

Responses

200

List of Payout Link objects.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

422

Invalid field

get/payout_links

Request samples

curl

curl "https://finix.sandbox-payments-api.com/payout_links" \
  -H "Finix-Version: 2022-02-01" \
  -u US9bhCUqoTxo7V6di8ceb3Td:e704591a-1972-4b41-9884-6a67f5d7cdbb

Response samples

application/json

{"_embedded": {"payout_links": [{"id": "payout_link_caKCWTF8wyp784FEN7fF5",
"additional_details": {"success_return_url": null,
"unsuccessful_return_url": null,
"expired_session_url": null,
"terms_of_service_url": "https://example.com/terms",
"expiration_in_minutes": 10080
},
"allowed_payout_operations": ["PUSH_TO_CARD"
],
"amount_details": {"total_amount": 100000,
"currency": "USD"
},
"application_id": "AP5Tq3MMxKwHYX7soDncrCQ3",
"branding": {"brand_color": "#0D121A",
"accent_color": "#0B5DBC",
"logo": "https://s3-us-west-2.amazonaws.com/payments-dashboard-assets/dashboard.finixpayments.com/2022-04-28-22_56_33-finix-logo-v2.png",
"icon": "",
"logo_alternative_text": null,
"button_font_color": "#FFFFFF"
},
"created_at": "2024-04-30T22:06:06.92597Z",
"items": [{"name": "Insurance Payout #2552",
"image_details": {"primary_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/8/88/Uninsured_cars_seized_by_police_in_Liverpool.JPG/220px-Uninsured_cars_seized_by_police_in_Liverpool.JPG",
"alternative_image_urls": [ ]
},
"price_details": {"amount": 100000,
"currency": "USD"
},
"description": "Car Damage",
"quantity": 1
}
],
"link_expires_at": "2024-05-07T22:06:06.928549Z",
"link_url": "https://live.sandbox-payments-checkout.com/payout_link?bearer_token=MDE4ZjMxMGItMmM1My03NmVjLTlhYzktZDI3ZmMyYThlNzQzLVBBWU9VVF9MSU5L",
"nickname": "Insurance Claim #2552",
"recipient_details": null,
"state": "ACTIVE",
"tags": {"collectPhoneNumber": "false",
"collectEmail": "false"
},
"updated_at": "2024-04-30T22:06:07.007377Z",
"_links": {"self": {"href": "https://finix.sandbox-payments-api.com/payout_links"
},
"next": {"href": "https://finix.sandbox-payments-api.com/payout_links?offset=0&sort=created_at,desc&limit=50&after_cursor=payout_link_ccjwNX9UuBmLmqUQk7SvT"
}
},
"page": {"limit": 100,
"next_cursor": "ZTyLnqRtGpWxuTMeOVjPbR7y"
}
}
]
}
}

Fetch a Payout Link

Retrieve the details of a previously created Payout Link.

Request

path Parameters

payout_link_id

required

string

The ID of the Payout Link.

header Parameters

Finix-Version

string

Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01

Responses

200

Response schema for creating a Payout Link.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

422

Invalid field

get/payout_links/{payout_link_id}

Request samples

curl

curl "https://finix.sandbox-payments-api.com/payout_links/payout_link_caydo4NPFJMoFhT5ZZfBf" \
  -H "Finix-Version: 2022-02-01" \
  -u US9bhCUqoTxo7V6di8ceb3Td:e704591a-1972-4b41-9884-6a67f5d7cdbb

Response samples

application/json

{"id": "payout_link_ches9gZg2WWM7ARM53pmP",
"additional_details": {"success_return_url": null,
"unsuccessful_return_url": null,
"expired_session_url": null,
"terms_of_service_url": "https://example.com/terms",
"expiration_in_minutes": 10080
},
"allowed_payout_operations": ["PUSH_TO_CARD"
],
"amount_details": {"total_amount": 100000,
"currency": "USD"
},
"application_id": "AP5Tq3MMxKwHYX7soDncrCQ3",
"branding": {"brand_color": "#0D121A",
"accent_color": "#0B5DBC",
"logo": "https://s3-us-west-2.amazonaws.com/payments-dashboard-assets/dashboard.finixpayments.com/2022-04-28-22_56_33-finix-logo-v2.png",
"icon": "",
"logo_alternative_text": null,
"button_font_color": "#FFFFFF"
},
"created_at": "2024-11-15T10:07:50.353254Z",
"items": [{"name": "Insurance Payout #2552",
"image_details": {"primary_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/8/88/Uninsured_cars_seized_by_police_in_Liverpool.JPG/220px-Uninsured_cars_seized_by_police_in_Liverpool.JPG",
"alternative_image_urls": [ ]
},
"price_details": {"amount": 100000,
"currency": "USD"
},
"description": "Car Damage",
"quantity": 1
}
],
"link_expires_at": "2024-11-22T10:07:50.335572Z",
"link_url": "https://link.sandbox-payments-checkout.com/Xjts64",
"nickname": "Insurance Claim #2552",
"recipient_details": null,
"state": "ACTIVE",
"tags": {"collectPhoneNumber": false,
"collectEmail": false
},
"updated_at": "2024-11-15T10:07:50.596865Z",
"_links": {"self": {"href": "https://finix.sandbox-payments-api.com/payout_links/payout_link_ches9gZg2WWM7ARM53pmP"
}
}
}

Update a Payout Link

Update an existing Payout Link resource.

Request

path Parameters

payout_link_id

required

string

The ID of the Payout Link.

header Parameters

Finix-Version

string

Default: 2018-01-01

Specify the API version of your request. For more details, see Versioning.

Example: 2022-02-01

Request Body schema: application/json

	object Object containing branding details for the `Payout Link`.
nickname	string A human-readable name for the resource.
state	string Used to update the state of the `Payout Link` to `DEACTIVATED`. Value: "DEACTIVATED"
	object or null Include up to 50 `key: value` pairs to annotate requests with custom metadata. Maximum character length for individual `keys` is 40. Maximum character length for individual `values` is 500. (For example, `order_number: 25`, `item_type: produce`, `department: sales`)

Responses

200

Response schema for creating a Payout Link.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

422

Invalid field

put/payout_links/{payout_link_id}

Request samples

curl

curl -i -X PUT \
  -u US9bhCUqoTxo7V6di8ceb3Td:e704591a-1972-4b41-9884-6a67f5d7cdbb \
  'https://finix.sandbox-payments-api.com/payout_links/payout_link_caydo4NPFJMoFhT5ZZfBf' \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -d '{
    "nickname": "Insurance Claim #2552",
    "tags": {
      "collectEmail": false,
      "collectPhoneNumber": false
    },
    "items": [
      {
        "name": "Insurance Payout #2552",
        "description": "Car Damage",
        "quantity": "1",
        "image_details": {
          "primary_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/8/88/Uninsured_cars_seized_by_police_in_Liverpool.JPG/220px-Uninsured_cars_seized_by_police_in_Liverpool.JPG"
        },
        "price_details": {
          "amount": 100000,
          "currency": "USD"
        }
      }
    ],
    "amount_details": {
      "total_amount": 100000,
      "currency": "USD"
    },
    "additional_details": {
      "expiration_in_minutes": 10080,
      "terms_of_service_url": "https://example.com/terms"
    },
    "branding": {
      "icon": "",
      "brand_color": "#0D121A",
      "accent_color": "#0B5DBC",
      "button_font_color": "#FFFFFF",
      "logo": "https://s3-us-west-2.amazonaws.com/payments-dashboard-assets/dashboard.finixpayments.com/2022-04-28-22_56_33-finix-logo-v2.png"
    }
  }'

Response samples

application/json

{"id": "payout_link_ches9gZg2WWM7ARM53pmP",
"additional_details": {"success_return_url": null,
"unsuccessful_return_url": null,
"expired_session_url": null,
"terms_of_service_url": "https://example.com/terms",
"expiration_in_minutes": 10080
},
"allowed_payout_operations": ["PUSH_TO_CARD"
],
"amount_details": {"total_amount": 100000,
"currency": "USD"
},
"application_id": "AP5Tq3MMxKwHYX7soDncrCQ3",
"branding": {"brand_color": "#0D121A",
"accent_color": "#0B5DBC",
"logo": "https://s3-us-west-2.amazonaws.com/payments-dashboard-assets/dashboard.finixpayments.com/2022-04-28-22_56_33-finix-logo-v2.png",
"icon": "",
"logo_alternative_text": null,
"button_font_color": "#FFFFFF"
},
"created_at": "2024-11-15T10:07:50.353254Z",
"items": [{"name": "Insurance Payout #2552",
"image_details": {"primary_image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/8/88/Uninsured_cars_seized_by_police_in_Liverpool.JPG/220px-Uninsured_cars_seized_by_police_in_Liverpool.JPG",
"alternative_image_urls": [ ]
},
"price_details": {"amount": 100000,
"currency": "USD"
},
"description": "Car Damage",
"quantity": 1
}
],
"link_expires_at": "2024-11-22T10:07:50.335572Z",
"link_url": "https://link.sandbox-payments-checkout.com/Xjts64",
"nickname": "Insurance Claim #2552",
"recipient_details": null,
"state": "ACTIVE",
"tags": {"collectPhoneNumber": false,
"collectEmail": false
},
"updated_at": "2024-11-15T10:07:50.596865Z",
"_links": {"self": {"href": "https://finix.sandbox-payments-api.com/payout_links/payout_link_ches9gZg2WWM7ARM53pmP"
}
}
}

Payout Links

Related Guides

Create a Payout Link

header Parameters

Request Body schema: application/json

List Payout Links

query Parameters

header Parameters

Fetch a Payout Link

path Parameters

header Parameters

Update a Payout Link

path Parameters

header Parameters

Request Body schema: application/json