Create payout

Payments

Transactions
Buyers
Checkout Sessions
Payment links
Payment options
Payouts
Refunds
Sessions
Settlement records

Instruments

Card schemes
Digital wallets
Gift cards
Payment methods
Payment method definitions

Vault

Account updater
Network tokens
Payment service tokens
Vault Forward
Vault Forward endpoints
Vault Forward authentication

Connections

All services
Payment services
Digital wallets
Anti-fraud services
Gift-card services

Dashboard

Flow
Merchant accounts
Reports
Report executions

Errors

POST

payouts

curl --request POST \
  --url https://api.{gr4vy_id}.gr4vy.app/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 1299,
  "currency": "USD",
  "payment_service_id": "a7d6b829-aea5-407d-ab7f-138784b5ad2c",
  "category": "online_gambling",
  "external_identifier": "payout-123",
  "buyer_id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
  "buyer_external_identifier": "user-789123",
  "buyer": {
    "external_identifier": "user-789123",
    "display_name": "John L.",
    "billing_details": {
      "first_name": "John",
      "last_name": "Lunn",
      "email_address": "john@example.com",
      "phone_number": "+1234567890",
      "address": {
        "city": "London",
        "country": "GB",
        "postal_code": "789123",
        "state": "Greater London",
        "state_code": "GB-LND",
        "house_number_or_name": "10",
        "line1": "10 Oxford Street",
        "line2": "New Oxford Court",
        "organization": "Gr4vy"
      },
      "tax_id": {
        "value": "12345678931",
        "kind": "gb.vat"
      }
    },
    "shipping_details": {
      "type": "shipping-details",
      "id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
      "buyer_id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
      "first_name": "John",
      "last_name": "Lunn",
      "email_address": "john@example.com",
      "phone_number": "+1234567890",
      "address": {
        "city": "London",
        "country": "GB",
        "postal_code": "789123",
        "state": "Greater London",
        "state_code": "GB-LND",
        "house_number_or_name": "10",
        "line1": "10 Oxford Street",
        "line2": "New Oxford Court",
        "organization": "Gr4vy"
      }
    },
    "account_number": "1234567"
  },
  "merchant": {
    "name": "Merchant",
    "identification_number": "<string>",
    "phone_number": "+1234567890",
    "url": "<string>",
    "statement_descriptor": "<string>",
    "merchant_category_code": "<string>",
    "address": {
      "city": "London",
      "country": "GB",
      "postal_code": "789123",
      "state": "Greater London",
      "state_code": "GB-LND",
      "house_number_or_name": "10",
      "line1": "10 Oxford Street",
      "line2": "New Oxford Court",
      "organization": "Gr4vy"
    }
  },
  "payment_method": {
    "method": "card",
    "number": "4111111111111111",
    "expiration_date": "11/25",
    "external_identifier": "card-323444",
    "scheme": "visa"
  },
  "connection_options": {
    "checkout-card": {
      "source_id": "<string>",
      "processing_channel_id": "<string>"
    }
  }
}'

{
  "type": "payout",
  "id": "8d3fe99b-1422-42e6-bbb3-932d95ae5f79",
  "merchant_account_id": "default",
  "amount": 1299,
  "currency": "USD",
  "created_at": "2022-01-01T12:00:00+00:00",
  "updated_at": "2022-01-01T12:00:00+00:00",
  "payment_service": {
    "type": "payment-service",
    "id": "stripe-card-faaad066-30b4-4997-a438-242b0752d7e1",
    "display_name": "Stripe (Main)",
    "method": "card",
    "payment_service_definition_id": "stripe-card"
  },
  "payment_service_payout_id": "example",
  "category": "online_gambling",
  "status": "pending",
  "external_identifier": "user-789123",
  "merchant": {
    "type": "merchant",
    "name": "Merchant",
    "identification_number": "<string>",
    "phone_number": "+1234567890",
    "url": "<string>",
    "statement_descriptor": "<string>",
    "merchant_category_code": "<string>",
    "address": {
      "city": "London",
      "country": "GB",
      "postal_code": "789123",
      "state": "Greater London",
      "state_code": "GB-LND",
      "house_number_or_name": "10",
      "line1": "10 Oxford Street",
      "line2": "New Oxford Court",
      "organization": "Gr4vy"
    }
  },
  "buyer": {
    "type": "buyer",
    "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
    "billing_details": {
      "type": "billing-details",
      "first_name": "John",
      "last_name": "Lunn",
      "email_address": "john@example.com",
      "phone_number": "+1234567890",
      "address": {
        "city": "London",
        "country": "GB",
        "postal_code": "789123",
        "state": "Greater London",
        "state_code": "GB-LND",
        "house_number_or_name": "10",
        "line1": "10 Oxford Street",
        "line2": "New Oxford Court",
        "organization": "Gr4vy"
      },
      "tax_id": {
        "value": "12345678931",
        "kind": "gb.vat"
      }
    },
    "display_name": "John L.",
    "external_identifier": "user-789123",
    "account_number": "1234567"
  },
  "payment_method": {
    "type": "payment-method",
    "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
    "approval_target": "any",
    "approval_url": "https://api.example.app.gr4vy.com/payment-methods/ffc88ec9-e1ee-45ba-993d-b5902c3b2a8c/approve",
    "country": "US",
    "currency": "USD",
    "details": {
      "bin": "412345",
      "card_type": "credit",
      "card_issuer_name": "Bank"
    },
    "expiration_date": "11/25",
    "external_identifier": "user-789123",
    "label": "1111",
    "last_replaced_at": "2023-07-26T19:23:00.000+00:00",
    "method": "card",
    "payment_account_reference": "V0010014629724763377327521982",
    "scheme": "visa",
    "fingerprint": "20eb353620155d2b5fc864cc46a73ea77cb92c725238650839da1813fa987a17"
  }
}

This endpoint requires the payouts.write scope.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request body for creating new payout.

amount

number

required

The amount to payout.

Required range: 1 <= x <= 99999999

Example:

1299

currency

string

required

The ISO-4217 currency code for the payout.

Example:

"USD"

payment_service_id

string

required

The ID of the payment service to use for the payout.

Example:

"a7d6b829-aea5-407d-ab7f-138784b5ad2c"

payment_method

object

required

The type of payment method to send funds too.

Response

201

application/json

Returns the created payout.

type

enum<string>

The type of this resource. Is always payout.

Available options:

payout

Example:

"payout"

string

The ID of a payout.

Example:

"8d3fe99b-1422-42e6-bbb3-932d95ae5f79"

merchant_account_id

string | null

The optional ID of the merchant account this payout should be assigned to.

Maximum length: 22

Example:

"default"

amount

integer

The monetary amount for this payout, in the smallest currency unit for the given currency, for example 1299 cents to create an authorization for $12.99.

Example:

1299

currency

string

A supported ISO-4217 currency code.

Example:

"USD"

created_at

string

The date and time when this payout was created.

Example:

"2022-01-01T12:00:00+00:00"

updated_at

string

The date and time when this payout was created.

Example:

"2022-01-01T12:00:00+00:00"

payment_service

object

The payment service used for this payout.

payment_service_payout_id

string | null

The ID of the payout in the underlying payment service.

Example:

"example"

category

enum<string>

The type of payout to process.

Available options:

online_gambling

Example:

"online_gambling"

status

enum<string>

The status of the payout.

Available options:

pending,

failed,

declined,

succeeded

Example:

"pending"

external_identifier

string | null

An external identifier that can be used to match the payout against your own records. This value needs to be unique for all buyers.

Required string length: 1 - 200

Example:

"user-789123"

merchant

object

The merchant details associated to this payout.

merchant.type

enum<string>

The type of this resource. Is always merchant.

Available options:

merchant

Example:

"merchant"

merchant.name

string

The name of the merchant.

Maximum length: 255

Example:

"Merchant"

merchant.identification_number

string

Unique value which identifies a merchant for processing transactions, also known as a MID.

Maximum length: 200

merchant.phone_number

string

The phone number for the merchant which should be formatted according to the E164 number standard.

Required string length: 1 - 50

Example:

"+1234567890"

merchant.url

string

Merchant website URL.

merchant.statement_descriptor

string

Value to explain charges or payments on bank statements.

Required string length: 5 - 22

merchant.merchant_category_code

string

Merchant classification for the type of goods or services it provides.

Required string length: 1 - 4

merchant.address

object

The address for the merchant.

buyer

object

The buyer used for this transaction.

buyer.type

enum<string>

The type of this resource. Is always buyer.

Available options:

buyer

Example:

"buyer"

buyer.id

string | null

The unique Gr4vy ID for this buyer.

Example:

"fe26475d-ec3e-4884-9553-f7356683f7f9"

buyer.billing_details

object

The billing details associated with the buyer, which include the address and tax ID.

buyer.billing_details.type

enum<string>

The type of this resource. Is always billing-details.

Available options:

billing-details

Example:

"billing-details"

buyer.billing_details.first_name

string | null

The first name(s) or given name of the buyer.

Required string length: 1 - 255

Example:

"John"

buyer.billing_details.last_name

string | null

The last name, or family name, of the buyer.

Required string length: 1 - 255

Example:

"Lunn"

buyer.billing_details.email_address

string | null

The email address of the buyer.

Required string length: 1 - 320

Example:

"john@example.com"

buyer.billing_details.phone_number

string | null

The phone number of the buyer. This number is formatted according to the E164 number standard.

Required string length: 1 - 50

Example:

"+1234567890"

buyer.billing_details.address

object

The billing address of the buyer.

buyer.billing_details.tax_id

object

The tax information associated with the billing details.

buyer.display_name

string | null

A unique name for this buyer which is used in the Gr4vy admin panel to give a buyer a human readable name.

Required string length: 1 - 200

Example:

"John L."

buyer.external_identifier

string | null

An external identifier that can be used to match the buyer against your own records.

Required string length: 1 - 200

Example:

"user-789123"

buyer.account_number

string | null

The source account number to perform an account funding transaction.

Required string length: 1 - 255

Example:

"1234567"

payment_method

object

The payment method used for this payout.

payment_method.type

enum<string>

payment-method.

Available options:

payment-method

Example:

"payment-method"

payment_method.id

string | null

The unique ID of the payment method.

Example:

"77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5"

payment_method.approval_target

enum<string> | null

The browser target that an approval URL must be opened in. If any or null, then there is no specific requirement.

Available options:

any,

new_window

Example:

"any"

payment_method.approval_url

string | null

The optional URL that the buyer needs to be redirected to to further authorize their payment.

Example:

"https://api.example.app.gr4vy.com/payment-methods/ffc88ec9-e1ee-45ba-993d-b5902c3b2a8c/approve"

payment_method.country

string | null

The 2-letter ISO code of the country this payment method can be used for. If this value is null the payment method may be used in multiple countries.

Example:

"US"

payment_method.currency

string | null

The ISO-4217 currency code that this payment method can be used for. If this value is null the payment method may be used for multiple currencies.

Example:

"USD"

payment_method.details

object

A credit or debit card payment method.

payment_method.expiration_date

string | null

The expiration date for this payment method. This is mostly used by cards where the card might have an expiration date.

Required string length: 5

Example:

"11/25"

payment_method.external_identifier

string | null

An external identifier that can be used to match the payment method against your own records.

Example:

"user-789123"

payment_method.label

string | null

A label for the payment method. This can be the last 4 digits for a card, or the email address for an alternative payment method.

Example:

"1111"

payment_method.last_replaced_at

string | null

The date and time when this card was last replaced.

When the Account Updater determines that new card details are available, existing details are not changed immediately. There are three scenarios in which the actual replacement occurs:

When this card has expired.
When only the expiration date changed.
When a transaction using this card is declined with any of the following codes:
- canceled_payment_method
- expired_payment_method
- unavailable_payment_method
- unknown_payment_method

When the replacement is applied, this field is updated. For non-card payment methods, the value of this field is always set to null.

Example:

"2023-07-26T19:23:00.000+00:00"

payment_method.method

enum<string>

The type of this payment method.

Available options:

afterpay,

alipay,

alipayhk,

applepay,

bacs,

bancontact,

banked,

becs,

bitpay,

boleto,

boost,

card,

cashapp,

chaseorbital,

checkout-session,

clearpay,

click-to-pay,

dana,

dcb,

dlocal,

ebanx,

efecty,

eps,

everydaypay,

gcash,

gift-card,

giropay,

givingblock,

gocardless,

googlepay,

googlepay_pan_only,

gopay,

grabpay,

id,

ideal,

kakaopay,

kcp,

klarna,

laybuy,

linepay,

linkaja,

maybankqrpay,

mercadopago,

multibanco,

multipago,

netbanking,

network-token,

oney_3x,

oney_4x,

oney_6x,

oney_10x,

oney_12x,

ovo,

oxxo,

payid,

paymaya,

paypal,

paypalpaylater,

payto,

venmo,

pix,

pse,

rabbitlinepay,

razorpay,

scalapay,

sepa,

shopeepay,

singteldash,

smartpay,

sofort,

spei,

stripedd,

thaiqr,

touchngo,

truemoney,

trustly,

trustlyeurope,

upi,

vipps,

waave,

webpay,

wechat,

zippay

Example:

"card"

payment_method.payment_account_reference

string | null

The payment account reference (PAR) returned by the card scheme. This is a unique reference to the underlying account that has been used to fund this payment method. This value will be unique if the same underlying account was used, regardless of the actual payment method used. For example, a network token or an Apple Pay device token will return the same PAR when possible.

The uniqueness of this value will depend on the card scheme, please refer to their documentation for further details. The availability of the PAR in our API depends on the availability of its value in the API of the payment service used for the transaction.

Example:

"V0010014629724763377327521982"

payment_method.scheme

enum<string> | null

An additional label used to differentiate different sub-types of a payment method. Most notably this can include the type of card used in a transaction. This field is null for the non-card payment methods. This represents the card scheme sent to the connector and it could be different from the actual card scheme that is being used by the PSP to process the transaction in the following situations: 1. use_additional_scheme transformation is used with the PAN instrument but we already have a PSP token for the card. 2. use_additional_scheme transformation is used but PSP has fallen back to the main card scheme internally.

Available options:

accel,

amex,

bancontact,

carte-bancaire,

cirrus,

culiance,

dankort,

diners-club,

discover,

eftpos-australia,

elo,

hipercard,

jcb,

maestro,

mastercard,

mir,

nyce,

other,

pulse,

rupay,

star,

uatp,

unionpay,

visa

Example:

"visa"

payment_method.fingerprint

string | null

The unique hash derived from the payment method identifier (e.g. card number).

Example:

"20eb353620155d2b5fc864cc46a73ea77cb92c725238650839da1813fa987a17"

Was this page helpful?

List payouts Get payout

curl --request POST \
  --url https://api.{gr4vy_id}.gr4vy.app/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 1299,
  "currency": "USD",
  "payment_service_id": "a7d6b829-aea5-407d-ab7f-138784b5ad2c",
  "category": "online_gambling",
  "external_identifier": "payout-123",
  "buyer_id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
  "buyer_external_identifier": "user-789123",
  "buyer": {
    "external_identifier": "user-789123",
    "display_name": "John L.",
    "billing_details": {
      "first_name": "John",
      "last_name": "Lunn",
      "email_address": "john@example.com",
      "phone_number": "+1234567890",
      "address": {
        "city": "London",
        "country": "GB",
        "postal_code": "789123",
        "state": "Greater London",
        "state_code": "GB-LND",
        "house_number_or_name": "10",
        "line1": "10 Oxford Street",
        "line2": "New Oxford Court",
        "organization": "Gr4vy"
      },
      "tax_id": {
        "value": "12345678931",
        "kind": "gb.vat"
      }
    },
    "shipping_details": {
      "type": "shipping-details",
      "id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
      "buyer_id": "8724fd24-5489-4a5d-90fd-0604df7d3b83",
      "first_name": "John",
      "last_name": "Lunn",
      "email_address": "john@example.com",
      "phone_number": "+1234567890",
      "address": {
        "city": "London",
        "country": "GB",
        "postal_code": "789123",
        "state": "Greater London",
        "state_code": "GB-LND",
        "house_number_or_name": "10",
        "line1": "10 Oxford Street",
        "line2": "New Oxford Court",
        "organization": "Gr4vy"
      }
    },
    "account_number": "1234567"
  },
  "merchant": {
    "name": "Merchant",
    "identification_number": "<string>",
    "phone_number": "+1234567890",
    "url": "<string>",
    "statement_descriptor": "<string>",
    "merchant_category_code": "<string>",
    "address": {
      "city": "London",
      "country": "GB",
      "postal_code": "789123",
      "state": "Greater London",
      "state_code": "GB-LND",
      "house_number_or_name": "10",
      "line1": "10 Oxford Street",
      "line2": "New Oxford Court",
      "organization": "Gr4vy"
    }
  },
  "payment_method": {
    "method": "card",
    "number": "4111111111111111",
    "expiration_date": "11/25",
    "external_identifier": "card-323444",
    "scheme": "visa"
  },
  "connection_options": {
    "checkout-card": {
      "source_id": "<string>",
      "processing_channel_id": "<string>"
    }
  }
}'

{
  "type": "payout",
  "id": "8d3fe99b-1422-42e6-bbb3-932d95ae5f79",
  "merchant_account_id": "default",
  "amount": 1299,
  "currency": "USD",
  "created_at": "2022-01-01T12:00:00+00:00",
  "updated_at": "2022-01-01T12:00:00+00:00",
  "payment_service": {
    "type": "payment-service",
    "id": "stripe-card-faaad066-30b4-4997-a438-242b0752d7e1",
    "display_name": "Stripe (Main)",
    "method": "card",
    "payment_service_definition_id": "stripe-card"
  },
  "payment_service_payout_id": "example",
  "category": "online_gambling",
  "status": "pending",
  "external_identifier": "user-789123",
  "merchant": {
    "type": "merchant",
    "name": "Merchant",
    "identification_number": "<string>",
    "phone_number": "+1234567890",
    "url": "<string>",
    "statement_descriptor": "<string>",
    "merchant_category_code": "<string>",
    "address": {
      "city": "London",
      "country": "GB",
      "postal_code": "789123",
      "state": "Greater London",
      "state_code": "GB-LND",
      "house_number_or_name": "10",
      "line1": "10 Oxford Street",
      "line2": "New Oxford Court",
      "organization": "Gr4vy"
    }
  },
  "buyer": {
    "type": "buyer",
    "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
    "billing_details": {
      "type": "billing-details",
      "first_name": "John",
      "last_name": "Lunn",
      "email_address": "john@example.com",
      "phone_number": "+1234567890",
      "address": {
        "city": "London",
        "country": "GB",
        "postal_code": "789123",
        "state": "Greater London",
        "state_code": "GB-LND",
        "house_number_or_name": "10",
        "line1": "10 Oxford Street",
        "line2": "New Oxford Court",
        "organization": "Gr4vy"
      },
      "tax_id": {
        "value": "12345678931",
        "kind": "gb.vat"
      }
    },
    "display_name": "John L.",
    "external_identifier": "user-789123",
    "account_number": "1234567"
  },
  "payment_method": {
    "type": "payment-method",
    "id": "77a76f7e-d2de-4bbc-ada9-d6a0015e6bd5",
    "approval_target": "any",
    "approval_url": "https://api.example.app.gr4vy.com/payment-methods/ffc88ec9-e1ee-45ba-993d-b5902c3b2a8c/approve",
    "country": "US",
    "currency": "USD",
    "details": {
      "bin": "412345",
      "card_type": "credit",
      "card_issuer_name": "Bank"
    },
    "expiration_date": "11/25",
    "external_identifier": "user-789123",
    "label": "1111",
    "last_replaced_at": "2023-07-26T19:23:00.000+00:00",
    "method": "card",
    "payment_account_reference": "V0010014629724763377327521982",
    "scheme": "visa",
    "fingerprint": "20eb353620155d2b5fc864cc46a73ea77cb92c725238650839da1813fa987a17"
  }
}