Payments
- Transactions
- Buyers
- Checkout Sessions
- 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
Create payout
Creates a new payout.
This endpoint requires the payouts.write scope.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Request body for creating new payout.
The amount to payout.
1 < x < 99999999The ISO-4217 currency code for the payout.
The ID of the payment service to use for the payout.
The type of payment method to send funds too.
The method to use.
card The 13-19 digit number for this card as it can be found on the front of the card.
13 - 19The expiration date of the card, formatted MM/YY.
5An external identifier that can be used to match the card against your own records.
The card scheme.
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 The type of payout to process.
online_gambling A value that can be used to match the payout against your own records.
1 - 200The ID of the buyer to send the payout.
The external_identifier of the buyer to send this payout to.
200Inline buyer details for the payout.
An external identifier that can be used to match the buyer against your own records. This value needs to be unique for all buyers.
1 - 200A unique name for this buyer which is used in the Gr4vy admin panel to give a buyer a human readable name.
1 - 200The optional billing details for the a buyer.
The first name(s) or given name for the buyer.
1 - 255The last name, or family name, of the buyer.
1 - 255The email address for the buyer.
1 - 320The phone number for the buyer which should be formatted according to the E164 number standard.
1 - 50The billing address for the buyer.
The city for the address.
1 - 100The country for the address in ISO 3166 format.
2The postal code or zip code for the address.
1 - 50The state, county, or province for the address.
1 - 255The first line of the address.
1 - 255The code of state, county, or province for the address in ISO 3166-2 format.
4 - 6The house number or name for the address. Not all payment services use this field but some do.
1 - 255The second line of the address.
1 - 255The optional name of the company or organisation to add to the address.
1 - 255The tax ID information associated with the billing details.
The tax ID for the buyer.
1 - 50The kind of tax ID.
ae.trn, au.abn, ar.dni, ar.cuil, ar.cuit, br.cnpj, br.cpf, ca.bn, ca.gst_hst, ca.pst_bc, ca.pst_mb, ca.pst_sk, ca.qst, ch.vat, cl.tin, es.cif, eu.vat, gb.vat, hk.br, id.nik, id.npwp, in.gst, jp.cn, jp.rn, kr.brn, li.uid, mx.curp, my.frp, my.itn, my.nric, my.sst, no.vat, nz.gst, ph.tin, ru.inn, ru.kpp, sa.vat, sg.gst, sg.uen, th.id, th.vat, tw.vat, us.ein, za.vat The optional shipping details for the buyer.
The type of this resource. Is always shipping-details.
shipping-details The unique ID for a buyer's shipping detail.
The unique ID for a buyer.
The first name(s) or given name of the buyer.
1 - 255The last name, or family name, of the buyer.
1 - 255The email address of the buyer.
1 - 320The phone number of the buyer. This number is formatted according to the E164 number standard.
1 - 50The physical shipping address associated to this buyer.
The city for the address.
1 - 100The country for the address in ISO 3166 format.
2The postal code or zip code for the address.
1 - 50The state, county, or province for the address.
1 - 255The code of state, county, or province for the address in ISO 3166-2 format.
4 - 6The house number or name for the address. Not all payment services use this field but some do.
1 - 255The first line of the address.
1 - 255The second line of the address.
1 - 255The optional name of the company or organisation to add to the address.
1 - 255Merchant information for the source of the payout.
The name of the merchant.
255Unique value which identifies a merchant for processing transactions, also known as a MID.
200The phone number for the merchant which should be formatted according to the E164 number standard.
1 - 50Merchant website URL.
Value to explain charges or payments on bank statements.
5 - 22Merchant classification for the type of goods or services it provides.
1 - 4The address for the merchant.
The city for the address.
1 - 100The country for the address in ISO 3166 format.
2The postal code or zip code for the address.
1 - 50The state, county, or province for the address.
1 - 255The code of state, county, or province for the address in ISO 3166-2 format.
4 - 6The house number or name for the address. Not all payment services use this field but some do.
1 - 255The first line of the address.
1 - 255The second line of the address.
1 - 255The optional name of the company or organisation to add to the address.
1 - 255Optional fields for processing payouts on specific payment services.
Response
The type of this resource. Is always payout.
payout The ID of a payout.
The optional ID of the merchant account this payout should be assigned to.
22The 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.
A supported ISO-4217 currency code.
The date and time when this payout was created.
The date and time when this payout was created.
The payment service used for this payout.
The type of this resource.
payment-service The ID of this payment service.
1 - 200The custom name set for this service.
1 - 50The payment method that this services handles.
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 The ID of the payment service definition used to create this service.
1 - 50The ID of the payout in the underlying payment service.
The type of payout to process.
online_gambling The status of the payout.
pending, failed, declined, succeeded An external identifier that can be used to match the payout against your own records. This value needs to be unique for all buyers.
1 - 200The merchant details associated to this payout.
The type of this resource. Is always merchant.
merchant The name of the merchant.
255Unique value which identifies a merchant for processing transactions, also known as a MID.
200The phone number for the merchant which should be formatted according to the E164 number standard.
1 - 50Merchant website URL.
Value to explain charges or payments on bank statements.
5 - 22Merchant classification for the type of goods or services it provides.
1 - 4The address for the merchant.
The city for the address.
1 - 100The country for the address in ISO 3166 format.
2The postal code or zip code for the address.
1 - 50The state, county, or province for the address.
1 - 255The code of state, county, or province for the address in ISO 3166-2 format.
4 - 6The house number or name for the address. Not all payment services use this field but some do.
1 - 255The first line of the address.
1 - 255The second line of the address.
1 - 255The optional name of the company or organisation to add to the address.
1 - 255The buyer used for this transaction.
The type of this resource. Is always buyer.
buyer The unique Gr4vy ID for this buyer.
The billing details associated with the buyer, which include the address and tax ID.
The type of this resource. Is always billing-details.
billing-details The first name(s) or given name of the buyer.
1 - 255The last name, or family name, of the buyer.
1 - 255The email address of the buyer.
1 - 320The phone number of the buyer. This number is formatted according to the E164 number standard.
1 - 50The billing address of the buyer.
The city for the address.
1 - 100The country for the address in ISO 3166 format.
2The postal code or zip code for the address.
1 - 50The state, county, or province for the address.
1 - 255The code of state, county, or province for the address in ISO 3166-2 format.
4 - 6The house number or name for the address. Not all payment services use this field but some do.
1 - 255The first line of the address.
1 - 255The second line of the address.
1 - 255The optional name of the company or organisation to add to the address.
1 - 255The tax information associated with the billing details.
The tax ID for the buyer.
1 - 50The kind of tax ID.
ae.trn, au.abn, ar.dni, ar.cuil, ar.cuit, br.cnpj, br.cpf, ca.bn, ca.gst_hst, ca.pst_bc, ca.pst_mb, ca.pst_sk, ca.qst, ch.vat, cl.tin, es.cif, eu.vat, gb.vat, hk.br, id.nik, id.npwp, in.gst, jp.cn, jp.rn, kr.brn, li.uid, mx.curp, my.frp, my.itn, my.nric, my.sst, no.vat, nz.gst, ph.tin, ru.inn, ru.kpp, sa.vat, sg.gst, sg.uen, th.id, th.vat, tw.vat, us.ein, za.vat A unique name for this buyer which is used in the Gr4vy admin panel to give a buyer a human readable name.
1 - 200An external identifier that can be used to match the buyer against your own records.
1 - 200The payment method used for this payout.
payment-method.
payment-method The unique ID of the payment method.
The browser target that an approval URL must be opened in. If any or null, then there is no specific requirement.
any, new_window The optional URL that the buyer needs to be redirected to to further authorize their payment.
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.
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.
The expiration date for this payment method. This is mostly used by cards where the card might have an expiration date.
5An external identifier that can be used to match the payment method against your own records.
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.
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_methodexpired_payment_methodunavailable_payment_methodunknown_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.
The type of this payment method.
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 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.
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.
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 The unique hash derived from the payment method identifier (e.g. card number).
Was this page helpful?