Instant Payout

Instant Payouts allow for advancing funds to a merchant account before the actual settlement of a payment. When confirmation is received from a payment processor that a transaction is completed and funds will arrive, an instant payout can be created from the funding account to the merchant account.

This feature is particularly useful for merchants who need immediate access to funds for cash flow purposes, rather than waiting for the standard settlement period which can take several business days.

Create Instant Payout

Use this endpoint to create a new instant payout. The system will immediately transfer the specified amount from the funding account to the merchant account, creating a debt that should be repaid when the original transaction settles.

Creates an instant payout.

Verb	POST
Url	https://api.s.unit.sh/instant-payouts
Required Scope	payments-write
Data Type	instantPayout
Timeout (Seconds)	5

Attributes

Name	Type	Description
amount	integer	The amount (in cents) to fund the merchant account.
description	string	Description of the instant payout.
tags	object	Optional. See Tags.
idempotencyKey	string	See Idempotency.

Relationships

Name	Type	Description
fundingAccount	JSON:API Relationship	Account the funds will be transferred from.
merchantAccount	JSON:API Relationship	End customer account to fund.

Example Request:

curl -X POST 'https://api.s.unit.sh/instant-payouts'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "instantPayout",
    "attributes": {
      "amount": 500000,
      "description": "Instant payout to merchant",
      "idempotencyKey": "idempotency-key"
    },
    "relationships": {
      "fundingAccount": {
        "data": {
          "type": "account",
          "id": "10009"
        }
      },
      "merchantAccount": {
        "data": {
          "type": "account",
          "id": "10040"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

The response contains the created instant payout with all relevant details including the current status and repayment information.

Attributes

Name	Type	Description
amount	integer	The amount (in cents) to fund the merchant account.
status	instantPayoutStatus	Instant payout status.
leftToRepayAmount	integer	The amount (in cents) left to repay.
description	string	Description of the instant payout.
tags	object	Optional. See Tags.
idempotencyKey	string	See Idempotency.

Relationships

Name	Type	Description
fundingAccount	JSON:API Relationship	Account the funds will be transferred from.
merchantAccount	JSON:API Relationship	End customer account to fund.
payoutTransaction	JSON:API Relationship	The transaction that was created to fund the merchant account.

Example Response:

{
  "data": {
    "type": "instantPayout",
    "id": "56",
    "attributes": {
      "amount": 5000,
      "status": "Paid",
      "leftToRepayAmount": 5000
    },
    "relationships": {
      "org": {
        "data": {
          "type": "org",
          "id": "56"
        }
      },
      "fundingAccount": {
        "data": {
          "type": "account",
          "id": "10009"
        }
      },
      "merchantAccount": {
        "data": {
          "type": "account",
          "id": "10040"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10040"
        }
      },
      "payoutTransaction": {
        "data": {
          "type": "transaction",
          "id": "130"
        }
      }
    }
  }
}

Instant Payout Status

The instant payout progresses through several states during its lifecycle. Understanding these statuses helps track the payout from creation to final repayment:

Name	Description
new	Initial state when an instant payout is first created but not yet processed.
paid	Indicates funds have successfully transferred from funding account to merchant account.
rejected	Occurs when the system fails to transfer funds from funding account for any reason.
partiallyRepaid	Indicates that a portion of the instant payout amount has been repaid, but not in full.
repaid	Final state when the instant payout has been fully repaid to the funding account.

Repay Instant Payout

Use this endpoint to repay an instant payout. If there are multiple paid payouts for the same merchant account, repayment will be done in the order of creation (FIFO).

Verb	POST
Url	https://api.s.unit.sh/instant-payouts/{id}/repay
Required Scope	payments-write
Data Type	repayInstantPayout
Timeout (Seconds)	5

Attributes

Name	Type	Description
idempotencyKey	string	See Idempotency.

Relationships

Name	Type	Description
account	JSON:API Relationship	Account that is targeted by the payment processor. This can be the funding account or a hidden account under the merchant.
merchantAccount	JSON:API Relationship	Merchant account that the instant payout was created for.
transaction	JSON:API Relationship	Payment settlement transaction from the payment processor.

Example Request:

curl -X POST 'https://api.s.unit.sh/instant-payouts/{id}/repay'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "repayInstantPayout",
    "attributes": {
      "idempotencyKey": "{{$randomUUID}}"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "10009"
        }
      },
      "merchantAccount": {
        "data": {
          "type": "account",
          "id": "10040"
        }
      },
      "transaction": {
        "data": {
          "type": "transaction",
          "id": "110"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

200 OK

Returns the updated instant payout with repayment information. The response will show the updated status and any changes to the leftToRepayAmount field.

Equal Amount Repayment

When the settlement transaction amount equals the instant payout amount, the instant payout is fully repaid and its status changes to repaid.

Partial Repayment

When the settlement transaction amount is less than the instant payout amount, a partial repayment occurs. The leftToRepayAmount is reduced by the transaction amount, and the status changes to partiallyRepaid.

Surplus Repayment

When the settlement transaction amount exceeds the instant payout amount, the system:

1. Fully repays the instant payout (status becomes repaid)
2. Creates a payout transaction to the merchant account with the surplus amount

Cross-Account Repayment

When the funding account differs from the account targeted by the payment processor, an additional instantPayoutRepayment transaction is created to transfer funds from the processor's target account to the original funding account.

Example Response:

{
  "data": {
    "type": "repayInstantPayout",
    "attributes": {
      "idempotencyKey": "{{$randomUUID}}"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": "10009"
        }
      },
      "merchantAccount": {
        "data": {
          "type": "account",
          "id": "10040"
        }
      },
      "transaction": {
        "data": {
          "type": "transaction",
          "id": "110"
        }
      }
    }
  }
}