PaySwitch
PaySwitch API Reference

Payouts

Server

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

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:
AF
AX
AL
DZ
AS
AD
AO
AI
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

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:
AF
AX
AL
DZ
AS
AD
AO
AI
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

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 for response

​object
​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.


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

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:
AF
AX
AL
DZ
AS
AD
AO
AI
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

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 for response

​object
​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.


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

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

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

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:
AF
AX
AL
DZ
AS
AD
AO
AI
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 - Update › Responses

Payout updated

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:
AF
AX
AL
DZ
AS
AD
AO
AI
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

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 for response

​object
​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.


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

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

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:
AF
AX
AL
DZ
AS
AD
AO
AI
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

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 for response

​object
​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.


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

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

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:
AF
AX
AL
DZ
AS
AD
AO
AI
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

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 for response

​object
​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.


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

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


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.
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

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


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

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

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:
AF
AX
AL
DZ
AS
AD
AO
AI
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 - Confirm › Responses

Payout updated

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:
AF
AX
AL
DZ
AS
AD
AO
AI
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

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 for response

​object
​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.


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.
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

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