Payouts

Create and manage payouts

Payouts - Create

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payouts/create

api-key (header)

Payouts - Create › Request Body

PayoutsCreateRequest

amount

integer · int64 · min: 0 · 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.,

currency

Currency · enum · required

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

Enum values:

AED

AFN

ALL

AMD

ANG

AOA

ARS

AUD

merchant_order_reference_id

string | null · maxLength: 255

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.

Example: merchant_order_ref_123

connector

array | null

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

Enum values:

phonypay

flexifai

fiftyfourpay

bitex

hypergate

maguapay

payadmit

milkypay

Example: ["wise","adyen"]

confirm

boolean | null

This field is used when merchant wants to confirm the payout, thus useful for the payout Confirm request. Ideally merchants should Create a payout, Update it (if required), then Confirm it.

Example: true

Default: false

payout_type

string · enum

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.

Enum values:

card

bank

wallet

bank_redirect

The payout method information required for carrying out a payout

object

auto_fulfill

boolean | null

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

Example: true

Default: false

object

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

return_url

string | null

The URL to redirect after the completion of the operation

Example: https://hyperswitch.io

business_country

string · enum

Enum values:

description

string | null

A description of the payout

Example: It's my first payout request

entity_type

string · enum

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

Enum values:

Individual

Company

NonProfit

PublicSector

NaturalPerson

lowercase

Personal

recurring

boolean | null

Specifies whether or not the payout request is recurring

Default: false

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

string · enum

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

Enum values:

instant

fast

regular

wire

cross_border

internal

payout_link

boolean | null

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

Default: false

object

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

session_expiry

integer | null · int32 · min: 0

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

Example: 900

payout_method_id

string | null

Identifier for payout method

object

Browser information to be used for 3DS 2.0

Payouts - Create › Responses

Payout created

PayoutCreateResponse

payout_id

string · minLength: 30 · maxLength: 30 · 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.

Example: 187282ab-40ef-47a9-9206-5099ba31e432

merchant_id

string · maxLength: 255 · required

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

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

Currency · enum · required

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

Enum values:

AED

AFN

ALL

AMD

ANG

AOA

ARS

AUD

auto_fulfill

boolean · required

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

Example: true

Default: false

customer_id

string · maxLength: 255 · required

The identifier for the customer object. If not provided the customer ID will be autogenerated.

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

CountryAlpha2 · enum · required

Enum values:

entity_type

PayoutEntityType · enum · required

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

Enum values:

Individual

Company

NonProfit

PublicSector

NaturalPerson

lowercase

Personal

recurring

boolean · required

Specifies whether or not the payout request is recurring

Default: false

status

PayoutStatus · enum · required

Enum values:

success

failed

cancelled

initiated

expired

reversed

pending

ineligible

profile_id

string · required

The business profile that is associated with this payout

merchant_order_reference_id

string | null · maxLength: 255

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.

Example: merchant_order_ref_123

connector

string | null

The connector used for the payout

Example: wise

payout_type

string · enum

Enum values:

card

bank

wallet

bank_redirect

The payout method information for response

object

Details of customer attached to this payment

business_label

string | null

Business label of the merchant for this payout

Example: food

description

string | null

A description of the payout

Example: It's my first payout request

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 | null · date-time

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

priority

string · enum

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

Enum values:

instant

fast

regular

wire

cross_border

internal

array | null

List of attempts

object

unified_code

string | null · maxLength: 255

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

Example: UE_000

unified_message

string | null · maxLength: 1024

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

Example: Invalid card details

payout_method_id

string | null

Identifier for payout method

object

A fee snapshot summary for one business transaction.

POST/payouts/create

curl https://paysw-wiki.lab.next-on.pro/dev-router/payouts/create \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 0,
  "currency": "AED",
  "routing": {
    "type": "single",
    "data": {
      "connector": "flexifai",
      "merchant_connector_id": "merchant_connector_id"
    }
  },
  "connector": [
    "wise",
    "adyen"
  ],
  "confirm": false,
  "payout_type": "card",
  "payout_method_data": {
    "card": {
      "card_number": "4242424242424242",
      "expiry_month": "expiry_month",
      "expiry_year": "expiry_year",
      "card_holder_name": "John Doe",
      "card_network": "Visa"
    }
  },
  "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": "email"
  },
  "auto_fulfill": false,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "tax_registration_id": "tax_registration_id",
    "document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "return_url": "https://hyperswitch.io",
  "business_country": "AF",
  "business_label": "food",
  "description": "It'\''s my first payout request",
  "entity_type": "Individual",
  "recurring": false,
  "metadata": {},
  "payout_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "profile_id": "profile_id",
  "priority": "instant",
  "payout_link": false,
  "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\"]}]",
    "form_layout": "tabs",
    "test_mode": false
  },
  "session_expiry": 900,
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "payout_method_id": "payout_method_id",
  "browser_info": {
    "color_depth": 0,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "language",
    "screen_height": 0,
    "screen_width": 0,
    "time_zone": 0,
    "ip_address": "ip_address",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "user_agent",
    "os_type": "os_type",
    "os_version": "os_version",
    "device_model": "device_model",
    "accept_language": "accept_language",
    "referer": "referer"
  }
}'

Example Request Body

{
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 0,
  "currency": "AED",
  "routing": {
    "type": "single",
    "data": {
      "connector": "flexifai",
      "merchant_connector_id": "merchant_connector_id"
    }
  },
  "connector": [
    "wise",
    "adyen"
  ],
  "confirm": false,
  "payout_type": "card",
  "payout_method_data": {
    "card": {
      "card_number": "4242424242424242",
      "expiry_month": "expiry_month",
      "expiry_year": "expiry_year",
      "card_holder_name": "John Doe",
      "card_network": "Visa"
    }
  },
  "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": "email"
  },
  "auto_fulfill": false,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "tax_registration_id": "tax_registration_id",
    "document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "return_url": "https://hyperswitch.io",
  "business_country": "AF",
  "business_label": "food",
  "description": "It's my first payout request",
  "entity_type": "Individual",
  "recurring": false,
  "metadata": {},
  "payout_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "profile_id": "profile_id",
  "priority": "instant",
  "payout_link": false,
  "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\"]}]",
    "form_layout": "tabs",
    "test_mode": false
  },
  "session_expiry": 900,
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "payout_method_id": "payout_method_id",
  "browser_info": {
    "color_depth": 0,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "language",
    "screen_height": 0,
    "screen_width": 0,
    "time_zone": 0,
    "ip_address": "ip_address",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "user_agent",
    "os_type": "os_type",
    "os_version": "os_version",
    "device_model": "device_model",
    "accept_language": "accept_language",
    "referer": "referer"
  }
}

json

Example Responses

{
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
  "merchant_id": "merchant_1668273825",
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 1000,
  "currency": "AED",
  "connector": "wise",
  "payout_type": "card",
  "payout_method_data": {
    "card": {
      "card_issuer": "card_issuer",
      "card_network": "Visa",
      "card_type": "card_type",
      "card_issuing_country": "card_issuing_country",
      "bank_code": "bank_code",
      "last4": "last4",
      "card_isin": "card_isin",
      "card_extended_bin": "card_extended_bin",
      "card_exp_month": "01",
      "card_exp_year": "2026",
      "card_holder_name": "John Doe"
    }
  },
  "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": "email"
  },
  "auto_fulfill": false,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "customer_document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "return_url": "https://hyperswitch.io",
  "business_country": "AF",
  "business_label": "food",
  "description": "It's my first payout request",
  "entity_type": "Individual",
  "recurring": false,
  "metadata": {},
  "merchant_connector_id": "mca_sAD3OZLATetvjLOYhUSy",
  "status": "success",
  "error_message": "Failed while verifying the card",
  "error_code": "E0001",
  "profile_id": "profile_id",
  "created": "2022-09-10T10:11:12Z",
  "connector_transaction_id": "S3FC9G9M2MVFDXT5",
  "priority": "instant",
  "attempts": [
    {
      "attempt_id": "attempt_id",
      "status": "success",
      "amount": 6583,
      "currency": "AED",
      "connector": "connector",
      "error_code": "error_code",
      "error_message": "error_message",
      "payment_method": "card",
      "payout_method_type": "ach",
      "connector_transaction_id": "connector_transaction_id",
      "cancellation_reason": "cancellation_reason",
      "unified_code": "UE_000",
      "unified_message": "Invalid card details",
      "fee_details": [
        {
          "reference_id": "reference_id",
          "created_at": "2024-01-01T00:00:00Z",
          "currency": "currency",
          "base_amount": 0,
          "merchant_commission_amount": 0,
          "provider_cost": 0,
          "margin": 0,
          "merchant_commission_rate": {},
          "provider_cost_rate": {},
          "merchant_commission_rule": "merchant_commission_rule",
          "provider_cost_rule": "provider_cost_rule"
        }
      ]
    }
  ],
  "payout_link": {
    "payout_link_id": "payout_link_id",
    "link": "link"
  },
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "unified_code": "UE_000",
  "unified_message": "Invalid card details",
  "payout_method_id": "payout_method_id",
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Payouts - Retrieve

GET

https://paysw-wiki.lab.next-on.pro/dev-router

/payouts/{payout_id}

api-key (header)

Payouts - Retrieve › path Parameters

payout_id

string · required

The identifier for payout

Payouts - Retrieve › query Parameters

force_sync

boolean | null

Sync with the connector to get the payout details (defaults to false)

Payouts - Retrieve › Responses

Payout retrieved

PayoutCreateResponse

payout_id

string · minLength: 30 · maxLength: 30 · 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.

Example: 187282ab-40ef-47a9-9206-5099ba31e432

merchant_id

string · maxLength: 255 · required

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

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

Currency · enum · required

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

Enum values:

AED

AFN

ALL

AMD

ANG

AOA

ARS

AUD

auto_fulfill

boolean · required

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

Example: true

Default: false

customer_id

string · maxLength: 255 · required

The identifier for the customer object. If not provided the customer ID will be autogenerated.

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

CountryAlpha2 · enum · required

Enum values:

entity_type

PayoutEntityType · enum · required

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

Enum values:

Individual

Company

NonProfit

PublicSector

NaturalPerson

lowercase

Personal

recurring

boolean · required

Specifies whether or not the payout request is recurring

Default: false

status

PayoutStatus · enum · required

Enum values:

success

failed

cancelled

initiated

expired

reversed

pending

ineligible

profile_id

string · required

The business profile that is associated with this payout

merchant_order_reference_id

string | null · maxLength: 255

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.

Example: merchant_order_ref_123

connector

string | null

The connector used for the payout

Example: wise

payout_type

string · enum

Enum values:

card

bank

wallet

bank_redirect

The payout method information for response

object

Details of customer attached to this payment

business_label

string | null

Business label of the merchant for this payout

Example: food

description

string | null

A description of the payout

Example: It's my first payout request

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 | null · date-time

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

priority

string · enum

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

Enum values:

instant

fast

regular

wire

cross_border

internal

array | null

List of attempts

object

unified_code

string | null · maxLength: 255

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

Example: UE_000

unified_message

string | null · maxLength: 1024

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

Example: Invalid card details

payout_method_id

string | null

Identifier for payout method

object

A fee snapshot summary for one business transaction.

GET/payouts/{payout_id}

curl https://paysw-wiki.lab.next-on.pro/dev-router/payouts/:payout_id \
  --header 'api-key: <api-key>'

Example Responses

{
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
  "merchant_id": "merchant_1668273825",
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 1000,
  "currency": "AED",
  "connector": "wise",
  "payout_type": "card",
  "payout_method_data": {
    "card": {
      "card_issuer": "card_issuer",
      "card_network": "Visa",
      "card_type": "card_type",
      "card_issuing_country": "card_issuing_country",
      "bank_code": "bank_code",
      "last4": "last4",
      "card_isin": "card_isin",
      "card_extended_bin": "card_extended_bin",
      "card_exp_month": "01",
      "card_exp_year": "2026",
      "card_holder_name": "John Doe"
    }
  },
  "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": "email"
  },
  "auto_fulfill": false,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "customer_document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "return_url": "https://hyperswitch.io",
  "business_country": "AF",
  "business_label": "food",
  "description": "It's my first payout request",
  "entity_type": "Individual",
  "recurring": false,
  "metadata": {},
  "merchant_connector_id": "mca_sAD3OZLATetvjLOYhUSy",
  "status": "success",
  "error_message": "Failed while verifying the card",
  "error_code": "E0001",
  "profile_id": "profile_id",
  "created": "2022-09-10T10:11:12Z",
  "connector_transaction_id": "S3FC9G9M2MVFDXT5",
  "priority": "instant",
  "attempts": [
    {
      "attempt_id": "attempt_id",
      "status": "success",
      "amount": 6583,
      "currency": "AED",
      "connector": "connector",
      "error_code": "error_code",
      "error_message": "error_message",
      "payment_method": "card",
      "payout_method_type": "ach",
      "connector_transaction_id": "connector_transaction_id",
      "cancellation_reason": "cancellation_reason",
      "unified_code": "UE_000",
      "unified_message": "Invalid card details",
      "fee_details": [
        {
          "reference_id": "reference_id",
          "created_at": "2024-01-01T00:00:00Z",
          "currency": "currency",
          "base_amount": 0,
          "merchant_commission_amount": 0,
          "provider_cost": 0,
          "margin": 0,
          "merchant_commission_rate": {},
          "provider_cost_rate": {},
          "merchant_commission_rule": "merchant_commission_rule",
          "provider_cost_rule": "provider_cost_rule"
        }
      ]
    }
  ],
  "payout_link": {
    "payout_link_id": "payout_link_id",
    "link": "link"
  },
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "unified_code": "UE_000",
  "unified_message": "Invalid card details",
  "payout_method_id": "payout_method_id",
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Payouts - Update

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payouts/{payout_id}

api-key (header)

Payouts - Update › path Parameters

payout_id

string · required

The identifier for payout

Payouts - Update › Request Body

PayoutUpdateRequest

merchant_order_reference_id

string | null · maxLength: 255

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.

Example: merchant_order_ref_123

amount

integer | null · int64 · min: 0

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

string · enum

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

Enum values:

AED

AFN

ALL

AMD

ANG

AOA

ARS

AUD

connector

array | null

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

Enum values:

phonypay

flexifai

fiftyfourpay

bitex

hypergate

maguapay

payadmit

milkypay

Example: ["wise","adyen"]

confirm

boolean | null

This field is used when merchant wants to confirm the payout, thus useful for the payout Confirm request. Ideally merchants should Create a payout, Update it (if required), then Confirm it.

Example: true

Default: false

payout_type

string · enum

Enum values:

card

bank

wallet

bank_redirect

The payout method information required for carrying out a payout

object

auto_fulfill

boolean | null

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

Example: true

Default: false

object

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

client_secret

string | null

It's a token used for client side verification.

Example: pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo

return_url

string | null

The URL to redirect after the completion of the operation

Example: https://hyperswitch.io

business_country

string · enum

Enum values:

description

string | null

A description of the payout

Example: It's my first payout request

entity_type

string · enum

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

Enum values:

Individual

Company

NonProfit

PublicSector

NaturalPerson

lowercase

Personal

recurring

boolean | null

Specifies whether or not the payout request is recurring

Default: false

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

priority

string · enum

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

Enum values:

instant

fast

regular

wire

cross_border

internal

payout_link

boolean | null

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

Default: false

object

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

session_expiry

integer | null · int32 · min: 0

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

Example: 900

payout_method_id

string | null

Identifier for payout method

object

Browser information to be used for 3DS 2.0

Payouts - Update › Responses

Payout updated

PayoutCreateResponse

payout_id

string · minLength: 30 · maxLength: 30 · 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.

Example: 187282ab-40ef-47a9-9206-5099ba31e432

merchant_id

string · maxLength: 255 · required

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

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

Currency · enum · required

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

Enum values:

AED

AFN

ALL

AMD

ANG

AOA

ARS

AUD

auto_fulfill

boolean · required

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

Example: true

Default: false

customer_id

string · maxLength: 255 · required

The identifier for the customer object. If not provided the customer ID will be autogenerated.

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

CountryAlpha2 · enum · required

Enum values:

entity_type

PayoutEntityType · enum · required

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

Enum values:

Individual

Company

NonProfit

PublicSector

NaturalPerson

lowercase

Personal

recurring

boolean · required

Specifies whether or not the payout request is recurring

Default: false

status

PayoutStatus · enum · required

Enum values:

success

failed

cancelled

initiated

expired

reversed

pending

ineligible

profile_id

string · required

The business profile that is associated with this payout

merchant_order_reference_id

string | null · maxLength: 255

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.

Example: merchant_order_ref_123

connector

string | null

The connector used for the payout

Example: wise

payout_type

string · enum

Enum values:

card

bank

wallet

bank_redirect

The payout method information for response

object

Details of customer attached to this payment

business_label

string | null

Business label of the merchant for this payout

Example: food

description

string | null

A description of the payout

Example: It's my first payout request

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 | null · date-time

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

priority

string · enum

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

Enum values:

instant

fast

regular

wire

cross_border

internal

array | null

List of attempts

object

unified_code

string | null · maxLength: 255

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

Example: UE_000

unified_message

string | null · maxLength: 1024

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

Example: Invalid card details

payout_method_id

string | null

Identifier for payout method

object

A fee snapshot summary for one business transaction.

POST/payouts/{payout_id}

curl https://paysw-wiki.lab.next-on.pro/dev-router/payouts/:payout_id \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 1000,
  "currency": "AED",
  "routing": {
    "type": "single",
    "data": {
      "connector": "flexifai",
      "merchant_connector_id": "merchant_connector_id"
    }
  },
  "connector": [
    "wise",
    "adyen"
  ],
  "confirm": false,
  "payout_type": "card",
  "payout_method_data": {
    "card": {
      "card_number": "4242424242424242",
      "expiry_month": "expiry_month",
      "expiry_year": "expiry_year",
      "card_holder_name": "John Doe",
      "card_network": "Visa"
    }
  },
  "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": "email"
  },
  "auto_fulfill": false,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "tax_registration_id": "tax_registration_id",
    "document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "return_url": "https://hyperswitch.io",
  "business_country": "AF",
  "business_label": "food",
  "description": "It'\''s my first payout request",
  "entity_type": "Individual",
  "recurring": false,
  "metadata": {},
  "payout_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "profile_id": "profile_id",
  "priority": "instant",
  "payout_link": false,
  "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\"]}]",
    "form_layout": "tabs",
    "test_mode": false
  },
  "session_expiry": 900,
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "payout_method_id": "payout_method_id",
  "browser_info": {
    "color_depth": 0,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "language",
    "screen_height": 0,
    "screen_width": 0,
    "time_zone": 0,
    "ip_address": "ip_address",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "user_agent",
    "os_type": "os_type",
    "os_version": "os_version",
    "device_model": "device_model",
    "accept_language": "accept_language",
    "referer": "referer"
  }
}'

Example Request Body

{
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 1000,
  "currency": "AED",
  "routing": {
    "type": "single",
    "data": {
      "connector": "flexifai",
      "merchant_connector_id": "merchant_connector_id"
    }
  },
  "connector": [
    "wise",
    "adyen"
  ],
  "confirm": false,
  "payout_type": "card",
  "payout_method_data": {
    "card": {
      "card_number": "4242424242424242",
      "expiry_month": "expiry_month",
      "expiry_year": "expiry_year",
      "card_holder_name": "John Doe",
      "card_network": "Visa"
    }
  },
  "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": "email"
  },
  "auto_fulfill": false,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "tax_registration_id": "tax_registration_id",
    "document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "return_url": "https://hyperswitch.io",
  "business_country": "AF",
  "business_label": "food",
  "description": "It's my first payout request",
  "entity_type": "Individual",
  "recurring": false,
  "metadata": {},
  "payout_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "profile_id": "profile_id",
  "priority": "instant",
  "payout_link": false,
  "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\"]}]",
    "form_layout": "tabs",
    "test_mode": false
  },
  "session_expiry": 900,
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "payout_method_id": "payout_method_id",
  "browser_info": {
    "color_depth": 0,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "language",
    "screen_height": 0,
    "screen_width": 0,
    "time_zone": 0,
    "ip_address": "ip_address",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "user_agent",
    "os_type": "os_type",
    "os_version": "os_version",
    "device_model": "device_model",
    "accept_language": "accept_language",
    "referer": "referer"
  }
}

json

Example Responses

{
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
  "merchant_id": "merchant_1668273825",
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 1000,
  "currency": "AED",
  "connector": "wise",
  "payout_type": "card",
  "payout_method_data": {
    "card": {
      "card_issuer": "card_issuer",
      "card_network": "Visa",
      "card_type": "card_type",
      "card_issuing_country": "card_issuing_country",
      "bank_code": "bank_code",
      "last4": "last4",
      "card_isin": "card_isin",
      "card_extended_bin": "card_extended_bin",
      "card_exp_month": "01",
      "card_exp_year": "2026",
      "card_holder_name": "John Doe"
    }
  },
  "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": "email"
  },
  "auto_fulfill": false,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "customer_document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "return_url": "https://hyperswitch.io",
  "business_country": "AF",
  "business_label": "food",
  "description": "It's my first payout request",
  "entity_type": "Individual",
  "recurring": false,
  "metadata": {},
  "merchant_connector_id": "mca_sAD3OZLATetvjLOYhUSy",
  "status": "success",
  "error_message": "Failed while verifying the card",
  "error_code": "E0001",
  "profile_id": "profile_id",
  "created": "2022-09-10T10:11:12Z",
  "connector_transaction_id": "S3FC9G9M2MVFDXT5",
  "priority": "instant",
  "attempts": [
    {
      "attempt_id": "attempt_id",
      "status": "success",
      "amount": 6583,
      "currency": "AED",
      "connector": "connector",
      "error_code": "error_code",
      "error_message": "error_message",
      "payment_method": "card",
      "payout_method_type": "ach",
      "connector_transaction_id": "connector_transaction_id",
      "cancellation_reason": "cancellation_reason",
      "unified_code": "UE_000",
      "unified_message": "Invalid card details",
      "fee_details": [
        {
          "reference_id": "reference_id",
          "created_at": "2024-01-01T00:00:00Z",
          "currency": "currency",
          "base_amount": 0,
          "merchant_commission_amount": 0,
          "provider_cost": 0,
          "margin": 0,
          "merchant_commission_rate": {},
          "provider_cost_rate": {},
          "merchant_commission_rule": "merchant_commission_rule",
          "provider_cost_rule": "provider_cost_rule"
        }
      ]
    }
  ],
  "payout_link": {
    "payout_link_id": "payout_link_id",
    "link": "link"
  },
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "unified_code": "UE_000",
  "unified_message": "Invalid card details",
  "payout_method_id": "payout_method_id",
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Payouts - Cancel

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payouts/{payout_id}/cancel

api-key (header)

Payouts - Cancel › path Parameters

payout_id

string · required

The identifier for payout

Payouts - Cancel › Request Body

PayoutCancelRequest

payout_id

string · minLength: 30 · maxLength: 30 · 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.

Example: 187282ab-40ef-47a9-9206-5099ba31e432

Payouts - Cancel › Responses

Payout cancelled

PayoutCreateResponse

payout_id

string · minLength: 30 · maxLength: 30 · 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.

Example: 187282ab-40ef-47a9-9206-5099ba31e432

merchant_id

string · maxLength: 255 · required

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

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

Currency · enum · required

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

Enum values:

AED

AFN

ALL

AMD

ANG

AOA

ARS

AUD

auto_fulfill

boolean · required

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

Example: true

Default: false

customer_id

string · maxLength: 255 · required

The identifier for the customer object. If not provided the customer ID will be autogenerated.

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

CountryAlpha2 · enum · required

Enum values:

entity_type

PayoutEntityType · enum · required

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

Enum values:

Individual

Company

NonProfit

PublicSector

NaturalPerson

lowercase

Personal

recurring

boolean · required

Specifies whether or not the payout request is recurring

Default: false

status

PayoutStatus · enum · required

Enum values:

success

failed

cancelled

initiated

expired

reversed

pending

ineligible

profile_id

string · required

The business profile that is associated with this payout

merchant_order_reference_id

string | null · maxLength: 255

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.

Example: merchant_order_ref_123

connector

string | null

The connector used for the payout

Example: wise

payout_type

string · enum

Enum values:

card

bank

wallet

bank_redirect

The payout method information for response

object

Details of customer attached to this payment

business_label

string | null

Business label of the merchant for this payout

Example: food

description

string | null

A description of the payout

Example: It's my first payout request

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 | null · date-time

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

priority

string · enum

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

Enum values:

instant

fast

regular

wire

cross_border

internal

array | null

List of attempts

object

unified_code

string | null · maxLength: 255

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

Example: UE_000

unified_message

string | null · maxLength: 1024

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

Example: Invalid card details

payout_method_id

string | null

Identifier for payout method

object

A fee snapshot summary for one business transaction.

POST/payouts/{payout_id}/cancel

curl https://paysw-wiki.lab.next-on.pro/dev-router/payouts/:payout_id/cancel \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432"
}'

Example Request Body

{
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432"
}

json

Example Responses

{
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
  "merchant_id": "merchant_1668273825",
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 1000,
  "currency": "AED",
  "connector": "wise",
  "payout_type": "card",
  "payout_method_data": {
    "card": {
      "card_issuer": "card_issuer",
      "card_network": "Visa",
      "card_type": "card_type",
      "card_issuing_country": "card_issuing_country",
      "bank_code": "bank_code",
      "last4": "last4",
      "card_isin": "card_isin",
      "card_extended_bin": "card_extended_bin",
      "card_exp_month": "01",
      "card_exp_year": "2026",
      "card_holder_name": "John Doe"
    }
  },
  "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": "email"
  },
  "auto_fulfill": false,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "customer_document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "return_url": "https://hyperswitch.io",
  "business_country": "AF",
  "business_label": "food",
  "description": "It's my first payout request",
  "entity_type": "Individual",
  "recurring": false,
  "metadata": {},
  "merchant_connector_id": "mca_sAD3OZLATetvjLOYhUSy",
  "status": "success",
  "error_message": "Failed while verifying the card",
  "error_code": "E0001",
  "profile_id": "profile_id",
  "created": "2022-09-10T10:11:12Z",
  "connector_transaction_id": "S3FC9G9M2MVFDXT5",
  "priority": "instant",
  "attempts": [
    {
      "attempt_id": "attempt_id",
      "status": "success",
      "amount": 6583,
      "currency": "AED",
      "connector": "connector",
      "error_code": "error_code",
      "error_message": "error_message",
      "payment_method": "card",
      "payout_method_type": "ach",
      "connector_transaction_id": "connector_transaction_id",
      "cancellation_reason": "cancellation_reason",
      "unified_code": "UE_000",
      "unified_message": "Invalid card details",
      "fee_details": [
        {
          "reference_id": "reference_id",
          "created_at": "2024-01-01T00:00:00Z",
          "currency": "currency",
          "base_amount": 0,
          "merchant_commission_amount": 0,
          "provider_cost": 0,
          "margin": 0,
          "merchant_commission_rate": {},
          "provider_cost_rate": {},
          "merchant_commission_rule": "merchant_commission_rule",
          "provider_cost_rule": "provider_cost_rule"
        }
      ]
    }
  ],
  "payout_link": {
    "payout_link_id": "payout_link_id",
    "link": "link"
  },
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "unified_code": "UE_000",
  "unified_message": "Invalid card details",
  "payout_method_id": "payout_method_id",
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Payouts - Fulfill

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payouts/{payout_id}/fulfill

api-key (header)

Payouts - Fulfill › path Parameters

payout_id

string · required

The identifier for payout

Payouts - Fulfill › Request Body

PayoutFulfillRequest

payout_id

string · minLength: 30 · maxLength: 30 · 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.

Example: 187282ab-40ef-47a9-9206-5099ba31e432

Payouts - Fulfill › Responses

Payout fulfilled

PayoutCreateResponse

payout_id

string · minLength: 30 · maxLength: 30 · 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.

Example: 187282ab-40ef-47a9-9206-5099ba31e432

merchant_id

string · maxLength: 255 · required

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

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

Currency · enum · required

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

Enum values:

AED

AFN

ALL

AMD

ANG

AOA

ARS

AUD

auto_fulfill

boolean · required

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

Example: true

Default: false

customer_id

string · maxLength: 255 · required

The identifier for the customer object. If not provided the customer ID will be autogenerated.

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

CountryAlpha2 · enum · required

Enum values:

entity_type

PayoutEntityType · enum · required

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

Enum values:

Individual

Company

NonProfit

PublicSector

NaturalPerson

lowercase

Personal

recurring

boolean · required

Specifies whether or not the payout request is recurring

Default: false

status

PayoutStatus · enum · required

Enum values:

success

failed

cancelled

initiated

expired

reversed

pending

ineligible

profile_id

string · required

The business profile that is associated with this payout

merchant_order_reference_id

string | null · maxLength: 255

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.

Example: merchant_order_ref_123

connector

string | null

The connector used for the payout

Example: wise

payout_type

string · enum

Enum values:

card

bank

wallet

bank_redirect

The payout method information for response

object

Details of customer attached to this payment

business_label

string | null

Business label of the merchant for this payout

Example: food

description

string | null

A description of the payout

Example: It's my first payout request

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 | null · date-time

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

priority

string · enum

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

Enum values:

instant

fast

regular

wire

cross_border

internal

array | null

List of attempts

object

unified_code

string | null · maxLength: 255

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

Example: UE_000

unified_message

string | null · maxLength: 1024

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

Example: Invalid card details

payout_method_id

string | null

Identifier for payout method

object

A fee snapshot summary for one business transaction.

POST/payouts/{payout_id}/fulfill

curl https://paysw-wiki.lab.next-on.pro/dev-router/payouts/:payout_id/fulfill \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432"
}'

Example Request Body

{
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432"
}

json

Example Responses

{
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
  "merchant_id": "merchant_1668273825",
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 1000,
  "currency": "AED",
  "connector": "wise",
  "payout_type": "card",
  "payout_method_data": {
    "card": {
      "card_issuer": "card_issuer",
      "card_network": "Visa",
      "card_type": "card_type",
      "card_issuing_country": "card_issuing_country",
      "bank_code": "bank_code",
      "last4": "last4",
      "card_isin": "card_isin",
      "card_extended_bin": "card_extended_bin",
      "card_exp_month": "01",
      "card_exp_year": "2026",
      "card_holder_name": "John Doe"
    }
  },
  "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": "email"
  },
  "auto_fulfill": false,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "customer_document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "return_url": "https://hyperswitch.io",
  "business_country": "AF",
  "business_label": "food",
  "description": "It's my first payout request",
  "entity_type": "Individual",
  "recurring": false,
  "metadata": {},
  "merchant_connector_id": "mca_sAD3OZLATetvjLOYhUSy",
  "status": "success",
  "error_message": "Failed while verifying the card",
  "error_code": "E0001",
  "profile_id": "profile_id",
  "created": "2022-09-10T10:11:12Z",
  "connector_transaction_id": "S3FC9G9M2MVFDXT5",
  "priority": "instant",
  "attempts": [
    {
      "attempt_id": "attempt_id",
      "status": "success",
      "amount": 6583,
      "currency": "AED",
      "connector": "connector",
      "error_code": "error_code",
      "error_message": "error_message",
      "payment_method": "card",
      "payout_method_type": "ach",
      "connector_transaction_id": "connector_transaction_id",
      "cancellation_reason": "cancellation_reason",
      "unified_code": "UE_000",
      "unified_message": "Invalid card details",
      "fee_details": [
        {
          "reference_id": "reference_id",
          "created_at": "2024-01-01T00:00:00Z",
          "currency": "currency",
          "base_amount": 0,
          "merchant_commission_amount": 0,
          "provider_cost": 0,
          "margin": 0,
          "merchant_commission_rate": {},
          "provider_cost_rate": {},
          "merchant_commission_rule": "merchant_commission_rule",
          "provider_cost_rule": "provider_cost_rule"
        }
      ]
    }
  ],
  "payout_link": {
    "payout_link_id": "payout_link_id",
    "link": "link"
  },
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "unified_code": "UE_000",
  "unified_message": "Invalid card details",
  "payout_method_id": "payout_method_id",
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Payouts - List

GET

https://paysw-wiki.lab.next-on.pro/dev-router

/payouts/list

api-key (header)

Payouts - List › query Parameters

customer_id

string · required

The identifier for customer

starting_after

string · required

A cursor for use in pagination, fetch the next list after some object

ending_before

string · required

A cursor for use in pagination, fetch the previous list before some object

limit

string · required

limit on the number of objects to return

created

string · required

The time at which payout is created

time_range

string · required

The time range for which objects are needed. TimeRange has two fields start_time and end_time from which objects can be filtered as per required scenarios (created_at, time less than, greater than etc).

Payouts - List › Responses

Payouts listed

PayoutListResponse

size

integer · min: 0 · required

The number of payouts included in the list

PayoutCreateResponse[] · required

The list of payouts response objects

total_count

integer | null · int64

The total number of available payouts for given constraints

GET/payouts/list

curl 'https://paysw-wiki.lab.next-on.pro/dev-router/payouts/list?customer_id=<string>&starting_after=<string>&ending_before=<string>&limit=<string>&created=<string>&time_range=<string>' \
  --header 'api-key: <api-key>'

Example Responses

{
  "size": 0,
  "data": [
    {
      "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
      "merchant_id": "merchant_1668273825",
      "merchant_order_reference_id": "merchant_order_ref_123",
      "amount": 1000,
      "currency": "AED",
      "connector": "wise",
      "payout_type": "card",
      "payout_method_data": {
        "card": {
          "card_issuer": "card_issuer",
          "card_network": "Visa",
          "card_type": "card_type",
          "card_issuing_country": "card_issuing_country",
          "bank_code": "bank_code",
          "last4": "last4",
          "card_isin": "card_isin",
          "card_extended_bin": "card_extended_bin",
          "card_exp_month": "01",
          "card_exp_year": "2026",
          "card_holder_name": "John Doe"
        }
      },
      "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": "email"
      },
      "auto_fulfill": false,
      "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
      "customer": {
        "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
        "name": "John Doe",
        "email": "johntest@test.com",
        "phone": "9123456789",
        "phone_country_code": "+1",
        "customer_document_details": {
          "document_type": "cpf",
          "document_number": "12345678911"
        }
      },
      "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
      "return_url": "https://hyperswitch.io",
      "business_country": "AF",
      "business_label": "food",
      "description": "It's my first payout request",
      "entity_type": "Individual",
      "recurring": false,
      "metadata": {},
      "merchant_connector_id": "mca_sAD3OZLATetvjLOYhUSy",
      "status": "success",
      "error_message": "Failed while verifying the card",
      "error_code": "E0001",
      "profile_id": "profile_id",
      "created": "2022-09-10T10:11:12Z",
      "connector_transaction_id": "S3FC9G9M2MVFDXT5",
      "priority": "instant",
      "attempts": [
        {
          "attempt_id": "attempt_id",
          "status": "success",
          "amount": 6583,
          "currency": "AED",
          "connector": "connector",
          "error_code": "error_code",
          "error_message": "error_message",
          "payment_method": "card",
          "payout_method_type": "ach",
          "connector_transaction_id": "connector_transaction_id",
          "cancellation_reason": "cancellation_reason",
          "unified_code": "UE_000",
          "unified_message": "Invalid card details",
          "fee_details": [
            {
              "reference_id": "reference_id",
              "created_at": "2024-01-01T00:00:00Z",
              "currency": "currency",
              "base_amount": 0,
              "merchant_commission_amount": 0,
              "provider_cost": 0,
              "margin": 0,
              "merchant_commission_rate": {},
              "provider_cost_rate": {},
              "merchant_commission_rule": "merchant_commission_rule",
              "provider_cost_rule": "provider_cost_rule"
            }
          ]
        }
      ],
      "payout_link": {
        "payout_link_id": "payout_link_id",
        "link": "link"
      },
      "email": "johntest@test.com",
      "name": "John Test",
      "phone": "9123456789",
      "phone_country_code": "+1",
      "unified_code": "UE_000",
      "unified_message": "Invalid card details",
      "payout_method_id": "payout_method_id",
      "fee_summary": {
        "currency": "currency",
        "base_amount": 0,
        "merchant_commission_amount": 0,
        "provider_cost": 0,
        "margin": 0,
        "merchant_commission_rate": {},
        "provider_cost_rate": {},
        "merchant_commission_rule": "merchant_commission_rule",
        "provider_cost_rule": "provider_cost_rule"
      }
    }
  ],
  "total_count": 0
}

json

application/json

Payouts - List using filters

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payouts/list

api-key (header)

Payouts - List using filters › Request Body

A type representing a range of time for filtering, including a mandatory start time and an optional end time.

PayoutListFilterConstraints

start_time

string · date-time · required

The start time to filter payments list or to get list of filters. To get list of filters start time is needed to be passed

currency

Currency · enum · required

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

Enum values:

AED

AFN

ALL

AMD

ANG

AOA

ARS

AUD

entity_type

PayoutEntityType · enum · required

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

Enum values:

Individual

Company

NonProfit

PublicSector

NaturalPerson

lowercase

Personal

end_time

string | null · date-time

The end time to filter payments list or to get list of filters. If not passed the default time is now

payout_id

string | null · minLength: 30 · maxLength: 30

The identifier for payout

Example: 187282ab-40ef-47a9-9206-5099ba31e432

merchant_order_reference_id

string | null · maxLength: 255

The merchant order reference ID for payout

Example: merchant_order_ref_123

profile_id

string | null

The identifier for business profile

customer_id

string | null

The identifier for customer

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44

limit

integer · int32 · min: 0

The limit on the number of objects. The default limit is 10 and max limit is 20

offset

integer | null · int32 · min: 0

The starting point within a list of objects

connector

array | null

The list of connectors to filter payouts list

Enum values:

phonypay

flexifai

fiftyfourpay

bitex

hypergate

maguapay

payadmit

milkypay

Example: ["wise","adyen"]

status

array | null

The list of payout status to filter payouts list

Enum values:

success

failed

cancelled

initiated

expired

reversed

pending

ineligible

Example: ["pending","failed"]

payout_method

array | null

The list of payout methods to filter payouts list

Enum values:

card

bank

wallet

bank_redirect

Example: ["bank","card"]

object[]

Column predicates. Combined with other fields using AND.

Payouts - List using filters › Responses

Payouts filtered

PayoutListResponse

size

integer · min: 0 · required

The number of payouts included in the list

PayoutCreateResponse[] · required

The list of payouts response objects

total_count

integer | null · int64

The total number of available payouts for given constraints

POST/payouts/list

curl https://paysw-wiki.lab.next-on.pro/dev-router/payouts/list \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "start_time": "2024-08-25T15:00:00Z",
  "end_time": "2024-08-25T15:00:00Z",
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
  "merchant_order_reference_id": "merchant_order_ref_123",
  "profile_id": "profile_id",
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "limit": 0,
  "offset": 0,
  "connector": [
    "wise",
    "adyen"
  ],
  "currency": "AED",
  "status": [
    "pending",
    "failed"
  ],
  "payout_method": [
    "bank",
    "card"
  ],
  "entity_type": "Individual",
  "filters": [
    {}
  ]
}'

Example Request Body

{
  "start_time": "2024-08-25T15:00:00Z",
  "end_time": "2024-08-25T15:00:00Z",
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
  "merchant_order_reference_id": "merchant_order_ref_123",
  "profile_id": "profile_id",
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "limit": 0,
  "offset": 0,
  "connector": [
    "wise",
    "adyen"
  ],
  "currency": "AED",
  "status": [
    "pending",
    "failed"
  ],
  "payout_method": [
    "bank",
    "card"
  ],
  "entity_type": "Individual",
  "filters": [
    {}
  ]
}

json

Example Responses

{
  "size": 0,
  "data": [
    {
      "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
      "merchant_id": "merchant_1668273825",
      "merchant_order_reference_id": "merchant_order_ref_123",
      "amount": 1000,
      "currency": "AED",
      "connector": "wise",
      "payout_type": "card",
      "payout_method_data": {
        "card": {
          "card_issuer": "card_issuer",
          "card_network": "Visa",
          "card_type": "card_type",
          "card_issuing_country": "card_issuing_country",
          "bank_code": "bank_code",
          "last4": "last4",
          "card_isin": "card_isin",
          "card_extended_bin": "card_extended_bin",
          "card_exp_month": "01",
          "card_exp_year": "2026",
          "card_holder_name": "John Doe"
        }
      },
      "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": "email"
      },
      "auto_fulfill": false,
      "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
      "customer": {
        "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
        "name": "John Doe",
        "email": "johntest@test.com",
        "phone": "9123456789",
        "phone_country_code": "+1",
        "customer_document_details": {
          "document_type": "cpf",
          "document_number": "12345678911"
        }
      },
      "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
      "return_url": "https://hyperswitch.io",
      "business_country": "AF",
      "business_label": "food",
      "description": "It's my first payout request",
      "entity_type": "Individual",
      "recurring": false,
      "metadata": {},
      "merchant_connector_id": "mca_sAD3OZLATetvjLOYhUSy",
      "status": "success",
      "error_message": "Failed while verifying the card",
      "error_code": "E0001",
      "profile_id": "profile_id",
      "created": "2022-09-10T10:11:12Z",
      "connector_transaction_id": "S3FC9G9M2MVFDXT5",
      "priority": "instant",
      "attempts": [
        {
          "attempt_id": "attempt_id",
          "status": "success",
          "amount": 6583,
          "currency": "AED",
          "connector": "connector",
          "error_code": "error_code",
          "error_message": "error_message",
          "payment_method": "card",
          "payout_method_type": "ach",
          "connector_transaction_id": "connector_transaction_id",
          "cancellation_reason": "cancellation_reason",
          "unified_code": "UE_000",
          "unified_message": "Invalid card details",
          "fee_details": [
            {
              "reference_id": "reference_id",
              "created_at": "2024-01-01T00:00:00Z",
              "currency": "currency",
              "base_amount": 0,
              "merchant_commission_amount": 0,
              "provider_cost": 0,
              "margin": 0,
              "merchant_commission_rate": {},
              "provider_cost_rate": {},
              "merchant_commission_rule": "merchant_commission_rule",
              "provider_cost_rule": "provider_cost_rule"
            }
          ]
        }
      ],
      "payout_link": {
        "payout_link_id": "payout_link_id",
        "link": "link"
      },
      "email": "johntest@test.com",
      "name": "John Test",
      "phone": "9123456789",
      "phone_country_code": "+1",
      "unified_code": "UE_000",
      "unified_message": "Invalid card details",
      "payout_method_id": "payout_method_id",
      "fee_summary": {
        "currency": "currency",
        "base_amount": 0,
        "merchant_commission_amount": 0,
        "provider_cost": 0,
        "margin": 0,
        "merchant_commission_rate": {},
        "provider_cost_rate": {},
        "merchant_commission_rule": "merchant_commission_rule",
        "provider_cost_rule": "provider_cost_rule"
      }
    }
  ],
  "total_count": 0
}

json

application/json

Payouts - Confirm

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payouts/{payout_id}/confirm

api-key (header)

Payouts - Confirm › path Parameters

payout_id

string · required

The identifier for payout

Payouts - Confirm › Request Body

PayoutConfirmRequest

client_secret

string · required

It's a token used for client side verification.

merchant_order_reference_id

string | null · maxLength: 255

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.

Example: merchant_order_ref_123

amount

integer | null · int64 · min: 0

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

string · enum

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

Enum values:

AED

AFN

ALL

AMD

ANG

AOA

ARS

AUD

connector

array | null

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

Enum values:

phonypay

flexifai

fiftyfourpay

bitex

hypergate

maguapay

payadmit

milkypay

Example: ["wise","adyen"]

payout_type

string · enum

Enum values:

card

bank

wallet

bank_redirect

The payout method information required for carrying out a payout

object

auto_fulfill

boolean | null

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

Example: true

Default: false

object

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

return_url

string | null

The URL to redirect after the completion of the operation

Example: https://hyperswitch.io

business_country

string · enum

Enum values:

description

string | null

A description of the payout

Example: It's my first payout request

entity_type

string · enum

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

Enum values:

Individual

Company

NonProfit

PublicSector

NaturalPerson

lowercase

Personal

recurring

boolean | null

Specifies whether or not the payout request is recurring

Default: false

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

priority

string · enum

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

Enum values:

instant

fast

regular

wire

cross_border

internal

payout_link

boolean | null

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

Default: false

object

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

session_expiry

integer | null · int32 · min: 0

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

Example: 900

payout_method_id

string | null

Identifier for payout method

object

Browser information to be used for 3DS 2.0

Payouts - Confirm › Responses

Payout updated

PayoutCreateResponse

payout_id

string · minLength: 30 · maxLength: 30 · 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.

Example: 187282ab-40ef-47a9-9206-5099ba31e432

merchant_id

string · maxLength: 255 · required

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

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

Currency · enum · required

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

Enum values:

AED

AFN

ALL

AMD

ANG

AOA

ARS

AUD

auto_fulfill

boolean · required

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

Example: true

Default: false

customer_id

string · maxLength: 255 · required

The identifier for the customer object. If not provided the customer ID will be autogenerated.

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

CountryAlpha2 · enum · required

Enum values:

entity_type

PayoutEntityType · enum · required

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

Enum values:

Individual

Company

NonProfit

PublicSector

NaturalPerson

lowercase

Personal

recurring

boolean · required

Specifies whether or not the payout request is recurring

Default: false

status

PayoutStatus · enum · required

Enum values:

success

failed

cancelled

initiated

expired

reversed

pending

ineligible

profile_id

string · required

The business profile that is associated with this payout

merchant_order_reference_id

string | null · maxLength: 255

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.

Example: merchant_order_ref_123

connector

string | null

The connector used for the payout

Example: wise

payout_type

string · enum

Enum values:

card

bank

wallet

bank_redirect

The payout method information for response

object

Details of customer attached to this payment

business_label

string | null

Business label of the merchant for this payout

Example: food

description

string | null

A description of the payout

Example: It's my first payout request

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 | null · date-time

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

priority

string · enum

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

Enum values:

instant

fast

regular

wire

cross_border

internal

array | null

List of attempts

object

unified_code

string | null · maxLength: 255

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

Example: UE_000

unified_message

string | null · maxLength: 1024

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

Example: Invalid card details

payout_method_id

string | null

Identifier for payout method

object

A fee snapshot summary for one business transaction.

POST/payouts/{payout_id}/confirm

curl https://paysw-wiki.lab.next-on.pro/dev-router/payouts/:payout_id/confirm \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '{
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 1000,
  "currency": "AED",
  "routing": {
    "type": "single",
    "data": {
      "connector": "flexifai",
      "merchant_connector_id": "merchant_connector_id"
    }
  },
  "connector": [
    "wise",
    "adyen"
  ],
  "payout_type": "card",
  "payout_method_data": {
    "card": {
      "card_number": "4242424242424242",
      "expiry_month": "expiry_month",
      "expiry_year": "expiry_year",
      "card_holder_name": "John Doe",
      "card_network": "Visa"
    }
  },
  "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": "email"
  },
  "auto_fulfill": false,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "tax_registration_id": "tax_registration_id",
    "document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "client_secret": "client_secret",
  "return_url": "https://hyperswitch.io",
  "business_country": "AF",
  "business_label": "food",
  "description": "It'\''s my first payout request",
  "entity_type": "Individual",
  "recurring": false,
  "metadata": {},
  "payout_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "profile_id": "profile_id",
  "priority": "instant",
  "payout_link": false,
  "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\"]}]",
    "form_layout": "tabs",
    "test_mode": false
  },
  "session_expiry": 900,
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "payout_method_id": "payout_method_id",
  "browser_info": {
    "color_depth": 0,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "language",
    "screen_height": 0,
    "screen_width": 0,
    "time_zone": 0,
    "ip_address": "ip_address",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "user_agent",
    "os_type": "os_type",
    "os_version": "os_version",
    "device_model": "device_model",
    "accept_language": "accept_language",
    "referer": "referer"
  }
}'

Example Request Body

{
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 1000,
  "currency": "AED",
  "routing": {
    "type": "single",
    "data": {
      "connector": "flexifai",
      "merchant_connector_id": "merchant_connector_id"
    }
  },
  "connector": [
    "wise",
    "adyen"
  ],
  "payout_type": "card",
  "payout_method_data": {
    "card": {
      "card_number": "4242424242424242",
      "expiry_month": "expiry_month",
      "expiry_year": "expiry_year",
      "card_holder_name": "John Doe",
      "card_network": "Visa"
    }
  },
  "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": "email"
  },
  "auto_fulfill": false,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "tax_registration_id": "tax_registration_id",
    "document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "client_secret": "client_secret",
  "return_url": "https://hyperswitch.io",
  "business_country": "AF",
  "business_label": "food",
  "description": "It's my first payout request",
  "entity_type": "Individual",
  "recurring": false,
  "metadata": {},
  "payout_token": "187282ab-40ef-47a9-9206-5099ba31e432",
  "profile_id": "profile_id",
  "priority": "instant",
  "payout_link": false,
  "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\"]}]",
    "form_layout": "tabs",
    "test_mode": false
  },
  "session_expiry": 900,
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "payout_method_id": "payout_method_id",
  "browser_info": {
    "color_depth": 0,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "language",
    "screen_height": 0,
    "screen_width": 0,
    "time_zone": 0,
    "ip_address": "ip_address",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "user_agent",
    "os_type": "os_type",
    "os_version": "os_version",
    "device_model": "device_model",
    "accept_language": "accept_language",
    "referer": "referer"
  }
}

json

Example Responses

{
  "payout_id": "187282ab-40ef-47a9-9206-5099ba31e432",
  "merchant_id": "merchant_1668273825",
  "merchant_order_reference_id": "merchant_order_ref_123",
  "amount": 1000,
  "currency": "AED",
  "connector": "wise",
  "payout_type": "card",
  "payout_method_data": {
    "card": {
      "card_issuer": "card_issuer",
      "card_network": "Visa",
      "card_type": "card_type",
      "card_issuing_country": "card_issuing_country",
      "bank_code": "bank_code",
      "last4": "last4",
      "card_isin": "card_isin",
      "card_extended_bin": "card_extended_bin",
      "card_exp_month": "01",
      "card_exp_year": "2026",
      "card_holder_name": "John Doe"
    }
  },
  "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": "email"
  },
  "auto_fulfill": false,
  "customer_id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
  "customer": {
    "id": "cus_y3oqhf46pyzuxjbcn2giaqnb44",
    "name": "John Doe",
    "email": "johntest@test.com",
    "phone": "9123456789",
    "phone_country_code": "+1",
    "customer_document_details": {
      "document_type": "cpf",
      "document_number": "12345678911"
    }
  },
  "client_secret": "pay_U42c409qyHwOkWo3vK60_secret_el9ksDkiB8hi6j9N78yo",
  "return_url": "https://hyperswitch.io",
  "business_country": "AF",
  "business_label": "food",
  "description": "It's my first payout request",
  "entity_type": "Individual",
  "recurring": false,
  "metadata": {},
  "merchant_connector_id": "mca_sAD3OZLATetvjLOYhUSy",
  "status": "success",
  "error_message": "Failed while verifying the card",
  "error_code": "E0001",
  "profile_id": "profile_id",
  "created": "2022-09-10T10:11:12Z",
  "connector_transaction_id": "S3FC9G9M2MVFDXT5",
  "priority": "instant",
  "attempts": [
    {
      "attempt_id": "attempt_id",
      "status": "success",
      "amount": 6583,
      "currency": "AED",
      "connector": "connector",
      "error_code": "error_code",
      "error_message": "error_message",
      "payment_method": "card",
      "payout_method_type": "ach",
      "connector_transaction_id": "connector_transaction_id",
      "cancellation_reason": "cancellation_reason",
      "unified_code": "UE_000",
      "unified_message": "Invalid card details",
      "fee_details": [
        {
          "reference_id": "reference_id",
          "created_at": "2024-01-01T00:00:00Z",
          "currency": "currency",
          "base_amount": 0,
          "merchant_commission_amount": 0,
          "provider_cost": 0,
          "margin": 0,
          "merchant_commission_rate": {},
          "provider_cost_rate": {},
          "merchant_commission_rule": "merchant_commission_rule",
          "provider_cost_rule": "provider_cost_rule"
        }
      ]
    }
  ],
  "payout_link": {
    "payout_link_id": "payout_link_id",
    "link": "link"
  },
  "email": "johntest@test.com",
  "name": "John Test",
  "phone": "9123456789",
  "phone_country_code": "+1",
  "unified_code": "UE_000",
  "unified_message": "Invalid card details",
  "payout_method_id": "payout_method_id",
  "fee_summary": {
    "currency": "currency",
    "base_amount": 0,
    "merchant_commission_amount": 0,
    "provider_cost": 0,
    "margin": 0,
    "merchant_commission_rate": {},
    "provider_cost_rate": {},
    "merchant_commission_rule": "merchant_commission_rule",
    "provider_cost_rule": "provider_cost_rule"
  }
}

json

application/json

Payouts - List available filters

POST

https://paysw-wiki.lab.next-on.pro/dev-router

/payouts/filter

api-key (header)

Payouts - List available filters › Request Body

A type representing a range of time for filtering, including a mandatory start time and an optional end time.

TimeRange

start_time

string · date-time · required

The start time to filter payments list or to get list of filters. To get list of filters start time is needed to be passed

end_time

string | null · date-time

The end time to filter payments list or to get list of filters. If not passed the default time is now

Payouts - List available filters › Responses

200

Filters listed

PayoutListFilters

connector

PayoutConnectors[] · required

The list of available connector filters

Enum values:

phonypay

flexifai

fiftyfourpay

bitex

hypergate

maguapay

payadmit

milkypay

currency

Currency[] · required

The list of available currency filters

Enum values:

AED

AFN

ALL

AMD

ANG

AOA

ARS

AUD

status

PayoutStatus[] · required

The list of available payout status filters

Enum values:

success

failed

cancelled

initiated

expired

reversed

pending

ineligible

payout_method

PayoutType[] · required

The list of available payout method filters

Enum values:

card

bank

wallet

bank_redirect

Disputes Event