Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
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.
{
    "amount": 20000,
    "currency": "USD",
    "payment_service_id": "30dd07ba-2b26-4d56-82cb-6b34c827b3d4",
    "buyer": {
        "display_name": "John Smith",
        "billing_details": {
            "first_name": "John",
            "last_name": "Smith",
            "email_address": "john@example.com",
            "address": {
                "postal_code": "789123",
            }
        }
    },
    "payment_method": {
        "method": "card",
        "number": "4242424242424242",
        "expiration_date": "01/30"
    }
}

​
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: 
{
    "amount": 20000,
    "currency": "USD",
    "payment_service_id": "30dd07ba-2b26-4d56-82cb-6b34c827b3d4",
    "buyer_id": "16727c7c-8ba2-4391-b4f8-7bddfa2f298c"
    "payment_method": {
        "method": "id",
        "id": "b6c67478-5b17-4110-ba2e-eb98790aad4f"
    }
}

​
Limitations

A few limitations can be expected when making payouts.
  • 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.