Create Payout

Create a new payout to send funds.

POST /payouts/create

Body Parameters

Only amount and currency are mandatory. Everything else is optional, and several fields are deprecated in favor of newer equivalents (noted below).

Parameter	Type	Required	Description
`amount`	integer	Yes	The payout amount, in the lowest denomination of the currency (e.g. cents for USD, paisa for GBP).
`currency`	string	Yes	The three-letter ISO 4217 currency code (e.g. `USD`, `EUR`, `GBP`).
`merchant_order_reference_id`	string	No	Your own unique identifier for this payout, used for reconciliation. Max 255 chars.
`payout_type`	string	No	One of `card`, `bank`, `wallet`, `bank_redirect`. Mandatory before the payout can be confirmed — can be set here or in a later Update call.
`payout_method_data`	object	No	Method-specific payout details. One of `card`, `bank_transfer`, `wallet`, `bank_redirect` or `passthrough` (see below).
`source_bank_data`	object	No	Source bank transfer details (same shape as `bank_transfer` payout method data).
`payout_token`	string	No	Reference to a previously stored payout method, used instead of supplying `payout_method_data` directly.
`payout_method_id`	string	No	Identifier for a saved payout method.
`customer`	object	No	Customer details (`id`, `name`, `email`, `phone`, `phone_country_code`, `tax_registration_id`, `document_details`). Creates a new customer or attaches an existing one. Preferred over the deprecated top-level customer fields below.
`customer_id`	string	No, deprecated	Use `customer.id` instead. Auto-generated if omitted.
`email`	string	No, deprecated	Use `customer.email` instead.
`name`	string	No, deprecated	Use `customer.name` instead.
`phone`	string	No, deprecated	Use `customer.phone` instead.
`phone_country_code`	string	No, deprecated	Use `customer.phone_country_code` instead.
`billing`	object	No	Billing address and contact info (`address`, `phone`, `email`).
`confirm`	boolean	No (default `false`)	Confirms the payout immediately. Typical flow is Create → Update → Confirm.
`auto_fulfill`	boolean	No (default `false`)	If `true`, confirms the payout without manual review — no further action required.
`recurring`	boolean	No (default `false`)	Whether this payout request is recurring.
`entity_type`	string	No	Type of entity receiving the payout: `Individual`, `Company`, `NonProfit`, `PublicSector`, `NaturalPerson`, `Personal`, or `lowercase`.
`priority`	string	No	Send priority: `instant`, `fast`, `regular`, `wire`, `cross_border`, or `internal`.
`business_country`	string	No	Two-letter ISO country code for the merchant's business.
`profile_id`	string	No	The business profile to use, if your merchant account has more than one. Defaults to the account's default profile.
`description`	string	No	Free-text description of the payout.
`return_url`	string	No	URL to redirect to after the operation completes.
`metadata`	object	No	Up to 50 key-value pairs (keys ≤ 40 chars, values ≤ 500 chars) for storing additional structured info.
`session_expiry`	integer	No	Seconds until the client secret expires (e.g. `900` for 15 minutes).
`payout_link`	boolean	No (default `false`)	If `true`, generates a payout link. Must be set at creation — cannot be changed on Update.
`payout_link_config`	object	No	Customization for the payout link (logo, merchant name, theme, enabled payment methods, form layout, test mode).
`browser_info`	object	yes	Browser details used for 3DS 2.0 (screen size, language, time zone, user agent, IP address, etc.).

payout_method_data is a discriminated object — supply exactly one top-level key: card, bank_transfer, wallet, bank_redirect, or passthrough. source_bank_data accepts the same shape as bank_transfer on its own.

`card`

Field	Type	Required	Description
`card_number`	string	Yes	The card number.
`expiry_month`	string	Yes	Card expiry month.
`expiry_year`	string	Yes	Card expiry year.
`card_holder_name`	string	Yes	Name on the card.
`card_network`	string	No	One of `Visa`, `Mastercard`, `AmericanExpress`, `JCB`, `DinersClub`, `Discover`, `CartesBancaires`, `UnionPay`, `Interac`, `RuPay`, `Maestro`, `Star`, `Pulse`, `Accel`, `Nyce`.

`bank_transfer`

One of the following, supplied directly (no payout_method_type discriminator):

Variant	Required fields	Optional fields
ACH	`bank_account_number`, `bank_routing_number`	`bank_name`, `bank_country_code`, `bank_city`, `account_holder_name`
BACS	`bank_account_number`, `bank_sort_code`	`bank_name`, `bank_country_code`, `bank_city`, `account_holder_name`
SEPA	`iban`, `bic`	`bank_name`, `bank_country_code`, `bank_city`, `account_holder_name`
Trustly	`iban`, `country_code`, `account_number`, `bank_number`	—
Pix	`bank_account_number`, `pix_key`, `emv`	`bank_name`, `bank_branch`, `tax_id`, `ispb`
Open Banking	`account_holder_name`, `iban`	—

`wallet`

Supply exactly one of:

Sub-field	Required fields	Notes
`apple_pay_decrypt`	`dpan`, `expiry_month`, `expiry_year`, `card_holder_name`	`card_network` optional.
`google_pay_decrypt`	`application_primary_account_number`, `expiry_month`, `expiry_year`, `card_holder_name`	`card_network` optional.
`paypal`	`email`, `telephone_number`, `paypal_id`	All three required.
`venmo`	`telephone_number`	—

`bank_redirect`

Supply exactly one of:

Sub-field	Required fields
`interac`	`email`
`open_banking_uk`	`account_holder_name`, `iban`

`bank_transfer` (and `source_bank_data`, same shape)

Discriminated by payout_method_type. Each variant requires that field plus its own fields:

`payout_method_type`	Required fields	Optional fields
`ach`	`bank_account_number`, `bank_routing_number`	`bank_name`, `bank_country_code`, `bank_city`, `account_holder_name`
`bacs`	`bank_account_number`, `bank_sort_code`	`bank_name`, `bank_country_code`, `bank_city`, `account_holder_name`
`sepa`	`iban`, `bic`	`bank_name`, `bank_country_code`, `bank_city`, `account_holder_name`
`pix`	`bank_account_number`	`bank_name`, `bank_branch`, `tax_id`, `ispb`
`pix_key`	`pix_key`	—
`pix_emv`	`emv` (QR code string)	—
`trustly`	`iban`, `bank_country_code`, `bank_account_number`, `bank_number`	—
`open_banking`	`account_holder_name`, `iban`	—

`passthrough`

Field	Type	Required	Description
`psp_token`	string	Yes	PSP token generated for the payout method.
`psp_customer_id`	string	Yes	PSP customer ID.
`token_type`	string	Yes	A `PaymentMethodType` value (e.g. `ach`, `sepa`, `paypal`, `apple_pay`, `google_pay`, etc. — large enum covering all supported method sub-types).

Request Example

curl -X POST 'https://api.rpayz.com/payouts/create' \
  -H "Content-Type: application/json" \
  -H "api-key: snd_YOUR_API_KEY" \
  -d '{
  "amount": 5000,
  "currency": "USD",
  "customer": {
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1"
  },
  "payout_type": "bank",
  "payout_method_data": {
    "bank_transfer": {
      "payout_method_type": "ach",
      "bank_account_number": "000123456",
      "bank_routing_number": "110000000",
      "account_holder_name": "John Doe"
    }
  },
  "description": "Vendor payment",
  "auto_fulfill": true
}'

curl -X POST 'https://api.rpayz.com/payouts/create' \  -H "Content-Type: application/json" \  -H "api-key: snd_YOUR_API_KEY" \  -d '{  "amount": 5000,  "currency": "USD",  "customer": {    "name": "John Doe",    "email": "johntest@test.com",    "phone": "9123456789",    "phone_country_code": "+1"  },  "payout_type": "bank",  "payout_method_data": {    "bank_transfer": {      "payout_method_type": "ach",      "bank_account_number": "000123456",      "bank_routing_number": "110000000",      "account_holder_name": "John Doe"    }  },  "description": "Vendor payment",  "auto_fulfill": true}'

Response

{
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
  "merchant_id": "1668273825",
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 5000,
  "currency": "USD",
  "payout_type": "bank",
  "payout_method_data": {
    "bank": {
      "bank_account_number": "0001****3456",
      "bank_routing_number": "110***000",
      "account_holder_name": "John Doe"
    }
  },
  "billing": null,
  "auto_fulfill": true,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1"
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "return_url": "https://example.com",
  "business_country": "US",
  "description": "Vendor payment",
  "entity_type": "Individual",
  "recurring": false,
  "metadata": null,
  "status": "requires_fulfillment",
  "error_message": null,
  "error_code": null,
  "profile_id": "pro_abc123",
  "created": "2024-01-22T10:00:00Z",
  "connector_transaction_id": null,
  "priority": null,
  "attempts": null,
  "payout_link": null,
  "unified_code": null,
  "unified_message": null,
  "payout_method_id": null
}

`status` values

success, failed, cancelled, initiated, expired, reversed, pending, ineligible, requires_creation, requires_confirmation, requires_payout_method_data, requires_fulfillment, requires_vendor_account_creation

Error response

400 — Missing mandatory fields (only amount and currency are strictly required to create a payout).