Wooshpay is able to make payouts to your bank account. You can view a list of all of your payouts in your bank account on the Dashboard. Also, you can retrieve the payout list by API.

Payout Status #

There are five states of one payout request. Once the payout is created, the initial state will be pending. When cancel API is called, the status will be canceled, leading to the cancellation of the payout process. When the request is submitted to the bank, the state turns to in_transit. Then it breaks down into two possibilities: if the bank processing fails, it will lead to Failed of the payout result; if the bank processing is successful, then it will lead to paid status.

Payout Speed #

While payout schedule refers to the cadence your funds are paid out on (for example, day of the week), payout speed refers to the amount of time it takes for your funds to become available. The payout speed varies per country and is typically expressed as T+X days. Some payment processors may start “T” from their internal settlement time, meaning when the funds land in their bank accounts.

“T” refers to transaction time, meaning the time of initial payment confirmation or capture. For example, if your account is based in a country with a T+3 standard payout speed and you’re on a manual payout schedule, your balance will be available to payout within 3 business days from the time you captured a payment.

Minimum Payout Amount #

The minimum payout amount is typically one base unit of the local currency. For example, in the US, the minimum payout is one US dollar, whereas in Singapore the minimum payout is one Singapore dollar.

Payout Speed and Minimum Amount #

The table above is a standard case. The Payout Speed may vary due to different banks, and it may take a few extra days. The type of business and the country you’re in can also affect payout timing.

Start your payout #

You can create a payout with Wooshpay API. In general, there are two scenarios for payouts：

1. Global Payouts
2. Payouts to China

Before creating a payout, there are some of the required parameters that should be specified :

• beneficiary : Beneficiary details should be provided in this object, if this is an initial payout that beneficiary_id is not used. ) .
• type : The type should be either business (for company) or payee (for individual)
• business : Required the business details including company_registered_name, address and additional_info.
• payee : Required the business details including address, additional_info.
• destination : Required the bank account or card information the payout was sent to.

Global Payouts #

Create a global payout

To create a new Global Payout by directly providing beneficiary information

For Company Request

{
  "beneficiary_data": {
    "type": "business",
    "business": {
      "company_registered_name": "XXX ltd",
      "address": {
        "line1": "Block 3A",
        "line2": "XX Park",
        "postal_code": "98109",
        "city": "Seattle",
        "state": "WA",
        "country": "USA"
      },
      "additional_info": {
        "business_registration_number": "32342353535334234MCA4",
        "legal_rep_first_name": "Ming",
        "legal_rep_last_name": "Zhang",
        "legal_rep_id_type": "NATIONAL_ID",
        "legal_rep_id_number": "233923874838920238X",
        "legal_rep_email": "[email protected]",
        "legal_rep_phone": "13727282938"
      }
    }
  },
  "amount": 666,
  "currency": "cny",
  "description": "You can add description here",
  "type": "bank_account",
  "destination_data": {
    "source": {
      "account_holder_name": "xxxx ltd",
      "account_holder_type": "company",
      "bank_name": "Bank of America",
      "country": "USA",
      "currency": "USD",
      "account_number": "6210000000000002"
    }
  }
}

Response

  {
      "id": "po_1654453881670729728",
      "object": "payout",
      "created": 1683287519000,
      "currency": "CNY",
      "amount": 666,
      "description": "You can add description here",
      "status": "pending",
      "destination": {
          "id": "ba_1654453883419754496",
          "object": "bank_account",
          "created": 1683287519000,
          "country": "USA",
          "currency": "USD",
          "fingerprint": "817902e3b6a2cf61eebc484f89467be650063413",
          "last4": "0002",
          "account_holder_name": "xxxx ltd",
          "account_holder_type": "company"
      },
      "livemode": false,
      "type": "bank_account",
      "method": "standard",
      "beneficiary": {
          "id": "bf_1654453881691701248",
          "object": "beneficiary",
          "type": "business",
          "business": {
              "address": {
                  "city": "Seattle",
                  "country": "USA",
                  "line1": "Block 3A",
                  "line2": "XX Park",
                  "state": "WA",
                  "postal_code": "98109"
              },
              "company_registered_name": "XXX ltd",
              "additional_info": {
                  "business_registration_number": "32342353535334234MCA4",
                  "legal_rep_first_name": "Ming",
                  "legal_rep_last_name": "Zhang",
                  "legal_rep_id_type": "NATIONAL_ID",
                  "legal_rep_id_number": "233923874838920238X",
                  "legal_rep_email": "[email protected]",
                  "legal_rep_phone": "13727282938"
              }
          }
      }
  }

For individual Request
To create a paypout by directly provieding beneficiary information

  {
    "beneficiary_data": {
      "type": "payee",
      "payee":{
          "address": {
          "line1": "### Ave",
          "line2": "#501",
          "postal_code": "98109",
          "city": "Seattle",
          "state": "WA",
          "country": "USA"
        },
      "additional_info": {
          "last_name":"Kale",
          "first_name":"Leo",
          "id_type":"NATIONAL_ID",
          "id_country_iso_code":"USA",
          "id_number":"234242423423434X",
          "email":"[email protected]",
          "phone":"1234534343"
        }
      }
    },
    "amount": 1000,
    "currency": "USD",
    "description": "You can add description here",
    "type": "bank_account",
    "destination_data": {
      "source": {
        "account_holder_name": "Leo Kale",
        "account_holder_type": "individual",
        "bank_name": "Bank of America",
        "country": "USA",
        "currency": "USD",
        "account_number": "6210000000000002"
      }
    }
  }

Response

  {
      "id": "po_1654455721024028672",
      "object": "payout",
      "created": 1683287958000,
      "currency": "USD",
      "amount": 1000,
      "description": "You can add description here",
      "status": "pending",
      "destination": {
          "id": "ba_1654455722777247744",
          "object": "bank_account",
          "created": 1683287957000,
          "country": "USA",
          "currency": "USD",
          "fingerprint": "3e27cccbe614f34d9b688b9eed46cea1cf9eee1d",
          "last4": "0002",
          "account_holder_name": "Leo Kale",
          "account_holder_type": "individual"
      },
      "livemode": false,
      "type": "bank_account",
      "method": "standard",
      "beneficiary": {
          "id": "bf_1654455721040805888",
          "object": "beneficiary",
          "type": "payee",
          "payee": {
              "address": {
                  "city": "Seattle",
                  "country": "USA",
                  "line1": "### Ave",
                  "line2": "#501",
                  "state": "WA",
                  "postal_code": "98109"
              },
              "additional_info": {
                  "email": "[email protected]",
                  "phone": "1234534343",
                  "name": "LeoKale",
                  "last_name": "Kale",
                  "first_name": "Leo",
                  "id_type": "NATIONAL_ID",
                  "id_country_iso_code": "USA",
                  "id_number": "234242423423434X"
              }
          }
      }
  }

Recurring payouts

If you already have ever payout to the beneficiary, you could create a payout using beneficiary_id, destination_id which is saved on the server and you can find it in the last response.

In the above case, beneficiary_id is "bf_1579357548861980672" and destination_id is "ba_1654455722777247744"

Request

{
  "beneficiary": "bf_1579357548861980672",
  "amount": 888,
  "currency": "USD",
  "description": "You can add description here",
  "type": "bank_account",
  "destination": "ba_1654455722777247744"
}

Payouts to China #

Create a new payout to China

The difference with global payouts is that you need to submit the payment_intents_id when requesting a payout to China.

Request

  {
    "beneficiary": "bf_1579357548861980672",
    "amount": 666,
    "currency": "cny",
    "description": "You can add description here",
    "type": "bank_account",
    "destination_data": {
      "source": {
        "account_holder_name": "xxxx ltd",
        "account_holder_type": "company",
        "bank_name": "Bank of China",
        "country": "CN",
        "currency": "CNY",
        "account_number": "6210000000000002"
      }
    },
    "payment_intents_id": [
      "pi_1577840204872417280"
    ]
  }

Create a Payout with compliance documents

If you need to submit compliance documents to us, there are three steps to creating a Payout with compliance documents

1. Upload the compliance documents using Create a file

Request

  curl --location --request POST 'https://apitest.wooshpay.com/v1/files' \
  --header 'Accept: application/json' \
  --header 'Authorization: Your key' \
  --header 'User-Agent: Apifox/1.0.0' \
  --form 'file=@"/路径/xxx.pdf"'

Response

  {
      "id": "file_1654416327596572672",
      "object": "file",
      "created": 1683278565516,
      "url": "https://oss.swooshtransfer.cn/oa/product/1654416327596572672_9gKPHbFsa5pUq47TafAMfVvJ.pdf",
      "type": "pdf",
      "filename": "1654416327596572672_9gKPHbFsa5pUq47TafAMfVvJ.pdf"
  }

2. Copy the URL on your response In the above case， the URL is https://oss.swooshtransfer.cn/oa/product/1654416327596572672_9gKPHbFsa5pUq47TafAMfVvJ.pdf
3. Apply metadata to the payout created

• metadata : It consists of two parts, the first part is the key and the second part is the value.
• eg: "metadata": { "compliance document": "Your document url", "key2": "value2", "...": "..." }

Request

  {
      {
    "beneficiary": "bf_1579357548861980672",
    "metadata": {
          "compliance document": "https://oss.swooshtransfer.cn/oa/product/1654416327596572672_9gKPHbFsa5pUq47TafAMfVvJ.pdf"
      },

    "amount": 666,
    "currency": "cny",
    "description": "You can add description here",
    "type": "bank_account",
    "destination_data": {
      "source": {
        "account_holder_name": "xxxx ltd",
        "account_holder_type": "company",
        "bank_name": "Bank of China",
        "country": "CN",
        "currency": "CNY",
        "account_number": "6210000000000002"
      }
    },
    "payment_intents_id": [
      "pi_1577840204872417280"
    ]
  }
  }

Responsed

  {
      "id": "po_1654421512435793920",
      "object": "payout",
      "created": 1683279802000,
      "currency": "CNY",
      "amount": 666,
      "description": "You can add description here",
      "metadata": {
          "compliance document": "https://oss.swooshtransfer.cn/oa/product/1654416327596572672_9gKPHbFsa5pUq47TafAMfVvJ.pdf"
      },
      "status": "pending",
      "destination": {
          "id": "ba_1654421514230956032",
          "object": "bank_account",
          "created": 1683279801000,
          "country": "CN",
          "currency": "CNY",
          "fingerprint": "4732b34681776e6b2383da452cbbabbcd2228d48",
          "last4": "0002",
          "account_holder_name": "xxxx ltd",
          "account_holder_type": "company"
      },
      "livemode": false,
      "type": "bank_account",
      "method": "standard",
      "beneficiary": {
          "id": "bf_1654421512456765440",
          "object": "beneficiary",
          "type": "business",
          "business": {
              "address": {
                  "city": "Beijing",
                  "country": "CN",
                  "line1": "Block 3A",
                  "line2": "XX Park",
                  "state": "Beijing",
                  "postal_code": "323111"
              },
              "company_registered_name": "XXX ltd",
              "additional_info": {
                  "business_registration_number": "32342353535334234MCA4",
                  "legal_rep_first_name": "Ming",
                  "legal_rep_last_name": "Zhang",
                  "legal_rep_id_type": "NATIONAL_ID",
                  "legal_rep_id_number": "233923874838920238X",
                  "legal_rep_email": "[email protected]",
                  "legal_rep_phone": "13727282938"
              }
          }
      },
      "payment_intents_id": [
          "pi_1577840204872417280"
      ]
  }

Payout failures #

If the bank account can’t receive a payout for any reason, the bank sends the funds back to us. This returns an error with the reason for the failure. It can take several business days for your bank to return the payout and inform us that it failed. If this happens, you’re notified in the Dashboard. Make sure that the bank account information you provide is correct. If it’s not (a typo in the account number, for example), payouts may be sent to another bank account holder.

Negative payouts #

Each payout reflects your available account balance at the time it was created. In some cases, you may have a negative account balance. For example, if you receive 100 USD in payments but refund 200 USD of prior payments, your account balance would be -100 USD. If you don’t receive further payments to balance out the negative amount, a new payout will fail.

Learn about the outcomes of your payout #

To know whether a payout to a bank account was successful, you need to set up a webhook.

The following Event Type are important when you make payouts to bank accounts, and you can create webhook to learn about the status of your payout.

• payout.canceled: Occurs whenever a payout is canceled.
• payout.created: Occurs whenever a payout is created.
• payout.failed: Occurs whenever a payout attempt fails.
• payout.paid: Occurs whenever a payout is expected to be available in the destination account. If the payout fails, a payout.failed notification is also sent, at a later time.
• payout.updated: Occurs whenever a payout is updated.

After identifying the events to monitor, you can refer to the webhook guide to Create a webhook.

Instant Payouts #

With Instant Payouts, sending funds to a supported bank account (in the United Kingdom) can be processed within a day. You can request Instant Payouts any day or time, including weekends and holidays, and funds typically appear in the associated bank account.