Skip to main content
Payouts allow transferring funds to third parties from accounts. Currently, the system supports Original Credit Transactions (OCT) via cards only, though support for additional instruments and payout use-cases is planned for the near future.

​
Supported connectors

The following card connectors support payouts. Each one needs payouts enabled by the payment service, and some need extra configuration in the Gr4vy dashboard. See each connector’s page for details. A result reported in the API response isn’t always final. For example, an Adyen payout is succeeded once Adyen accepts it, and an ACI Worldwide payout can stay pending. See each connector’s page for details.

​
Creating a payout

To create a new payout, the following details need to be provided.
  • The amount & currency to pay out to the recipient
  • The card instrument to pay out to; this can be either a stored card or inline card details
  • The ID of the payment service to process the request via
  • The buyer (recipient) details in the form of an inline buyer record, or the ID/external identifier of a stored buyer.

​
Stored buyer or payment method

The buyer object can be replaced with a previously stored buyer using either the buyer_id or the buyer_external_identifier. Likewise, a previously stored payment method can be used:

​
Payout category

The category field sets the type of payout. The only supported value today is online_gambling, and connectors that send a purpose or funds transfer code to the card scheme use the code for gambling payouts. Contact Gr4vy before using payouts for other use cases, such as merchant disbursements or wallet withdrawals.

​
Buyer and merchant details

Send the recipient’s first and last name in the buyer’s billing_details. Most payment services pass the name to the card scheme, and some decline the payout without it. Include the billing address where you have it. The optional merchant object describes the source of the funds. Some connectors use it, for example to set the description the recipient sees. If you send it, several of its fields are required. See the API specification for the full list.

​
Payout status and webhooks

A payout has one of the following statuses:
  • succeeded - The payment service accepted the payout.
  • pending - Gr4vy is waiting for the payment service to confirm the result.
  • declined - The payment service or card issuer declined the payout.
  • failed - The payout failed for an internal or external reason.
Some payment services confirm the result in the API response. Others return pending first and send the result to Gr4vy in a webhook later. Configure the payment service’s webhooks as described on its connector page, and listen for the payout.* webhook events to learn the result. Not every connector processes every webhook, so a status can change at the payment service without Gr4vy seeing it.

​
Limitations

A few limitations can be expected when making payouts.
  • Payouts are sent to the payment_service_id in the request. They aren’t routed through Flow.
  • Some payment services may have strict requirements for the buyer billing details passed as part of the request. Please see the PSP’s developer documentation for more details.
  • Some payment services may require payouts to be explicitly enabled. Please contact the PSP’s support team for more details.
  • Some payment services may require additional fields to be supplied that are specific to that integration. For this the connection_options object has been introduced in the API. Please see the API specification for more details.