Payouts - Confirm

POST /payouts/{payout_id}/confirm

Payouts - Confirm

cURL

curl --request POST \
  --url https://sandbox.hyperswitch.io/payouts/{payout_id}/confirm \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data @- <<EOF
{
  "client_secret": "<string>",
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 1000,
  "routing": {
    "type": "single",
    "data": {
      "merchant_connector_id": "<string>"
    }
  },
  "connector": [
    "wise",
    "adyen"
  ],
  "payout_method_data": {
    "card": {
      "card_number": "4242424242424242",
      "expiry_month": "<string>",
      "expiry_year": "<string>",
      "card_holder_name": "John Doe"
    }
  },
  "source_bank_data": {
    "bank_account_number": "000123456",
    "bank_routing_number": "110000000",
    "payout_method_type": "ach",
    "bank_name": "Deutsche Bank",
    "bank_city": "California",
    "account_holder_name": "John Doe"
  },
  "billing": {
    "address": {
      "city": "New York",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "<string>"
  },
  "auto_fulfill": true,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "[e-mail]",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "tax_registration_id": "<string>",
    "document_details": {
      "document_number": "12345678911"
    },
    "date_of_birth": "1990-01-31"
  },
  "return_url": "https://hyperswitch.io",
  "business_label": "food",
  "description": "It's my first payout request",
  "billing_descriptor": {
    "reference": "<string>",
    "statement_descriptor": "<string>"
  },
  "recurring": false,
  "metadata": {},
  "payout_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "profile_id": "<string>",
  "payout_link": true,
  "payout_link_config": {
    "logo": "https://hyperswitch.io/favicon.ico",
    "merchant_name": "Hyperswitch",
    "theme": "#4285F4",
    "payout_link_id": "pm_collect_link_2bdacf398vwzq5n422S1",
    "enabled_payment_methods": "[{\"payment_method\": \"bank_transfer\", \"payment_method_types\": [\"ach\", \"bacs\"]}]",
    "test_mode": false
  },
  "session_expiry": 900,
  "email": "[e-mail]",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "payout_method_id": "<string>",
  "browser_info": {
    "color_depth": 1,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "<string>",
    "screen_height": 1,
    "screen_width": 1,
    "time_zone": 123,
    "ip_address": "<string>",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "<string>",
    "os_type": "<string>",
    "os_version": "<string>",
    "device_model": "<string>",
    "accept_language": "<string>",
    "referer": "<string>"
  }
}
EOF

200

{
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
  "merchant_id": "merchant_1668273825",
  "amount": 1000,
  "currency": "AED",
  "auto_fulfill": true,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "return_url": "https://hyperswitch.io",
  "business_country": "AF",
  "entity_type": "Individual",
  "recurring": false,
  "status": "success",
  "profile_id": "<string>",
  "merchant_order_reference_id": "merchant_order_ref_123",
  "connector": "wise",
  "payout_type": "card",
  "payout_method_data": {
    "card": {
      "card_exp_month": "01",
      "card_exp_year": "2026",
      "card_holder_name": "John Doe",
      "card_issuer": "<string>",
      "card_network": "Visa",
      "card_type": "<string>",
      "card_issuing_country": "<string>",
      "bank_code": "<string>",
      "last4": "<string>",
      "card_isin": "<string>",
      "card_extended_bin": "<string>"
    }
  },
  "source_bank_data": {
    "card": {
      "card_exp_month": "01",
      "card_exp_year": "2026",
      "card_holder_name": "John Doe",
      "card_issuer": "<string>",
      "card_network": "Visa",
      "card_type": "<string>",
      "card_issuing_country": "<string>",
      "bank_code": "<string>",
      "last4": "<string>",
      "card_isin": "<string>",
      "card_extended_bin": "<string>"
    }
  },
  "billing": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "<string>"
  },
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "[e-mail]",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "customer_document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "business_label": "food",
  "description": "It's my first payout request",
  "billing_descriptor": {
    "reference": "<string>",
    "statement_descriptor": "<string>"
  },
  "metadata": {},
  "merchant_connector_id": "mca_sAD3OZLATetvjLOYhUSy",
  "error_message": "Failed while verifying the card",
  "error_code": "E0001",
  "created": "2022-09-10T10:11:12Z",
  "connector_transaction_id": "S3FC9G9M2MVFDXT5",
  "connector_eligibility_reference_id": "8ad8bf30-5789-52be-a80a-72908abf5f9d",
  "priority": "instant",
  "attempts": [
    {
      "attempt_id": "<string>",
      "status": "success",
      "amount": 6583,
      "currency": "AED",
      "connector": "<string>",
      "error_code": "<string>",
      "error_message": "<string>",
      "payment_method": "card",
      "payout_method_type": "ach",
      "connector_transaction_id": "<string>",
      "cancellation_reason": "<string>",
      "unified_code": "UE_000",
      "unified_message": "Invalid card details"
    }
  ],
  "payout_link": {
    "payout_link_id": "<string>",
    "link": "<string>"
  },
  "email": "[e-mail]",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "unified_code": "UE_000",
  "unified_message": "Invalid card details",
  "payout_method_id": "<string>"
}

Authorizations

api-key · string · header · required

Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.

Path Parameters

payout_id · string · required

The identifier for payout

Body

application/json

client_secret · string · required

It's a token used for client side verification.

merchant_order_reference_id · string | null

Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.

Maximum string length: 255

Example:

"merchant_order_ref_123"

amount · integer<int64> | null

The payout amount. Amount for the payout in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc.,

Required range: x >= 0

Example:

1000

currency · enum<string> | null

The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.

Available options: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STD, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW, ZWL

routing · object

Option 1

Option 2

Option 3

Option 4

Option 5

Show child attributes

connector · enum<string>[] | null

This field allows the merchant to manually select a connector with which the payout can go through.

Available options: adyen, adyenplatform, cybersource, deutschebank, ebanx, gigadat, gotyme_sanlam, loonio, nomupay, nuvei, payone, paypal, stripe, truelayer, trustly, wise, worldpay, worldpayxml, envoy, itaubank, santander

Example:

["wise", "adyen"]

payout_type · enum<string> | null

The payout_type of the payout request is a mandatory field for confirming the payouts. It should be specified in the Create request. If not provided, it must be updated in the Payout Update request before it can be confirmed.

Available options: card, bank, wallet, bank_redirect

payout_method_data · object

The payout method information required for carrying out a payout

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Show child attributes

source_bank_data · object

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Option 8

Option 9

Option 10

Show child attributes

billing · object | null

Show child attributes

auto_fulfill · boolean | null · default: false

Set to true to confirm the payout without review, no further action required

Example:

true

customer_id · string | null · deprecated

The identifier for the customer object. If not provided the customer ID will be autogenerated. Deprecated: Use customer_id instead.

Maximum string length: 255

Example:

"cus_y3oqhf46pyzuxjbcn2giaqnb44"

customer · object | null

Passing this object creates a new customer or attaches an existing customer to the payment

Show child attributes

return_url · string | null

The URL to redirect after the completion of the operation

Example:

"https://hyperswitch.io"

business_country · enum<string> | null

Available options: AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, US

business_label · string | null · deprecated

Business label of the merchant for this payout. Deprecated: Use profile_id instead.

Example:

"food"

description · string | null

A description of the payout

Example:

"It's my first payout request"

billing_descriptor · object | null

Billing descriptor information for a payout.

Show child attributes

entity_type · enum<string> | null

Type of entity to whom the payout is being carried out to, select from the given list of options

Available options: Individual, Company, NonProfit, PublicSector, NaturalPerson, lowercase, Personal

recurring · boolean | null · default: false

Specifies whether or not the payout request is recurring

metadata · object | null

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.

payout_token · string | null

Provide a reference to a stored payout method, used to process the payout.

Example:

"187282ab-40ef-47a9-9206-5099ba31e432"

profile_id · string | null

The business profile to use for this payout, especially if there are multiple business profiles associated with the account, otherwise default business profile associated with the merchant account will be used.

priority · enum<string> | null

The send method which will be required for processing payouts, check options for better understanding.

Available options: instant, fast, regular, wire, cross_border, internal

payout_link · boolean | null · default: false

Whether to get the payout link (if applicable). Merchant need to specify this during the Payout Create, this field can not be updated during Payout Update.

Example:

true

payout_link_config · object | null

Custom payout link config for the particular payout, if payout link is to be generated.

Show child attributes

session_expiry · integer<int32> | null

Will be used to expire client secret after certain amount of time to be supplied in seconds (900) for 15 mins

Required range: x >= 0

Example:

900

email · string | null · deprecated

Customer's email. Deprecated: Use customer object instead.

Maximum string length: 255

Example:

"[e-mail]"

name · string | null · deprecated

Customer's name. Deprecated: Use customer object instead.

Maximum string length: 255

Example:

"John Test"

phone · string | null · deprecated

Customer's phone. Deprecated: Use customer object instead.

Maximum string length: 255

Example:

"9123456789"

phone_country_code · string | null · deprecated

Customer's phone country code. Deprecated: Use customer object instead.

Maximum string length: 255

Example:

"+1"

payout_method_id · string | null

Identifier for payout method

browser_info · object | null

Browser information to be used for 3DS 2.0

Show child attributes

Response

200

application/json

Payout updated

payout_id · string · required

Unique identifier for the payout. This ensures idempotency for multiple payouts that have been done by a single merchant. This field is auto generated and is returned in the API response.

Required string length: 30

Example:

"187282ab-40ef-47a9-9206-5099ba31e432"

merchant_id · string · required

This is an identifier for the merchant account. This is inferred from the API key provided during the request

Maximum string length: 255

Example:

"merchant_1668273825"

amount · integer<int64> · required

The payout amount. Amount for the payout in lowest denomination of the currency. (i.e) in cents for USD denomination, in paisa for INR denomination etc.,

Example:

1000

currency · enum<string> · required

The three-letter ISO 4217 currency code (e.g., "USD", "EUR") for the payment amount. This field is mandatory for creating a payment.

Available options: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STD, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW, ZWL

auto_fulfill · boolean · default: false · required

Set to true to confirm the payout without review, no further action required

Example:

true

customer_id · string · required · deprecated

The identifier for the customer object. If not provided the customer ID will be autogenerated. Deprecated: Use the customer object instead.

Maximum string length: 255

Example:

"cus_y3oqhf46pyzuxjbcn2giaqnb44"

client_secret · string · required

It's a token used for client side verification.

Example:

"pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo"

return_url · string · required

The URL to redirect after the completion of the operation

Example:

"https://hyperswitch.io"

business_country · enum<string> · required

Available options: AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, KH, CM, CA, CV, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CU, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IR, IQ, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KP, KR, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MK, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, NC, NZ, NI, NE, NG, NU, NF, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RE, RO, RU, RW, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SZ, SE, CH, SY, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW, US

entity_type · enum<string> · required

Type of entity to whom the payout is being carried out to, select from the given list of options

Available options: Individual, Company, NonProfit, PublicSector, NaturalPerson, lowercase, Personal

recurring · boolean · default: false · required

Specifies whether or not the payout request is recurring

status · enum<string> · required

Available options: success, failed, cancelled, initiated, expired, reversed, pending, ineligible, not_permitted, requires_creation, requires_confirmation, requires_payout_method_data, requires_fulfillment, requires_vendor_account_creation

profile_id · string · required

The business profile that is associated with this payout

merchant_order_reference_id · string | null

Your unique identifier for this payout or order. This ID helps you reconcile payouts on your system. If provided, it is passed to the connector if supported.

Maximum string length: 255

Example:

"merchant_order_ref_123"

connector · string | null

The connector used for the payout

Example:

"wise"

payout_type · enum<string> | null

The payout_type of the payout request is a mandatory field for confirming the payouts. It should be specified in the Create request. If not provided, it must be updated in the Payout Update request before it can be confirmed.

Available options: card, bank, wallet, bank_redirect

payout_method_data · object

The payout method information for response

Option 1

Option 2

Option 3

Option 4

Option 5

Show child attributes

source_bank_data · object

The payout method information for response

Option 1

Option 2

Option 3

Option 4

Option 5

Show child attributes

billing · object | null

Show child attributes

customer · object | null

Details of customer attached to this payment

Show child attributes

business_label · string | null · deprecated

Business label of the merchant for this payout. Deprecated: Use profile_id instead.

Example:

"food"

description · string | null

A description of the payout

Example:

"It's my first payout request"

billing_descriptor · object | null

Billing descriptor information for a payout.

Show child attributes

metadata · object | null

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.

merchant_connector_id · string | null

Unique identifier of the merchant connector account

Example:

"mca_sAD3OZLATetvjLOYhUSy"

error_message · string | null

If there was an error while calling the connector the error message is received here

Example:

"Failed while verifying the card"

error_code · string | null

If there was an error while calling the connectors the code is received here

Example:

"E0001"

created · string<date-time> | null

Time when the payout was created

Example:

"2022-09-10T10:11:12Z"

connector_transaction_id · string | null

Underlying processor's payout resource ID

Example:

"S3FC9G9M2MVFDXT5"

connector_eligibility_reference_id · string | null

Underlying processor's reference ID for the payout eligibility check

Example:

"8ad8bf30-5789-52be-a80a-72908abf5f9d"

priority · enum<string> | null

The send method which will be required for processing payouts, check options for better understanding.

Available options: instant, fast, regular, wire, cross_border, internal

attempts · object[] | null

List of attempts

Show child attributes

payout_link · object | null

Show child attributes

email · string | null · deprecated

Customer's email. Deprecated: Use customer object instead.

Maximum string length: 255

Example:

"[e-mail]"

name · string | null · deprecated

Customer's name. Deprecated: Use customer object instead.

Maximum string length: 255

Example:

"John Test"

phone · string | null · deprecated

Customer's phone. Deprecated: Use customer object instead.

Maximum string length: 255

Example:

"9123456789"

phone_country_code · string | null · deprecated

Customer's phone country code. Deprecated: Use customer object instead.

Maximum string length: 255

Example:

"+1"

unified_code · string | null

(This field is not live yet) Error code unified across the connectors is received here in case of errors while calling the underlying connector

Maximum string length: 255

Example:

"UE_000"

unified_message · string | null

(This field is not live yet) Error message unified across the connectors is received here in case of errors while calling the underlying connector

Maximum string length: 1024

Example:

"Invalid card details"

payout_method_id · string | null

Identifier for payout method