Manage scheduled payouts

DocsCurrent

Last updated: Oct 22nd, 5:38am

You can set up daily automatic withdrawals for your merchants to transfer their money to their associated bank accounts. The payout transfer frequency is daily. The cutoff is aligned from midnight to midnight (24 hours), and the balance from the previous day's transactions is withdrawn to the attached bank account.

Scheduled payouts support only one currency for each merchant.

Set up automatic withdrawals

Use the merchant onboarding API to set up auto-withdrawals for your merchants.

Sample code

Create managed account

1curl --location --request POST '{{host}}/v3/customer/managed-accounts' \
2--header 'Authorization: Bearer ACCESS-TOKEN' \
3--header 'Content-Type: application/json' \
4--data '
5{
6  "external_id": "{{$guid}}",
7  "legal_country_code": "US",
8  "individual_owners": [
9    {
10      "citizenship": "US",
11      "names": [
12        {
13          "type": "LEGAL",
14          "given_name": "John",
15          "surname": "Doe"
16        }
17      ],
18      "addresses": [
19        {
20          "type": "HOME",
21          "address_line_1": "7700 Eastport Pkwy",
22          "admin_area_2": "La Vista",
23          "admin_area_1": "NE",
24          "postal_code": "68128",
25          "country_code": "US"
26        }
27      ],
28      "birth_details": {
29        "date_of_birth": "1970-04-01"
30      },
31      "identification_documents": [
32        {
33          "type": "SOCIAL_SECURITY_NUMBER",
34          "issuing_country_code": "US",
35          "identification_number": "718913411"
36        }
37      ]
38    }
39  ],
40  "business_entity": {
41    "type": "CORPORATION",
42    "merchant_category_code": "0742",
43    "incorporation_details": {
44      "incorporation_country_code": "US",
45      "incorporation_date": "2010-06-01"
46    },
47    "names": [
48      {
49        "type": "LEGAL",
50        "business_name": "Generic Merchant"
51      }
52    ],
53    "addresses": [
54      {
55        "type": "BUSINESS",
56        "address_line_1": "7702 Eastport Pkwy",
57        "admin_area_2": "La Vista",
58        "admin_area_1": "NE",
59        "postal_code": "68128",
60        "country_code": "US"
61      }
62    ],
63    "office_bearers": [
64      {
65        "addresses": [
66          {
67            "address_line_1": "7701 Eastport Pkwy",
68            "admin_area_1": "NE",
69            "admin_area_2": "La Vista",
70            "country_code": "US",
71            "postal_code": "68128",
72            "type": "HOME"
73          }
74        ],
75        "birth_details": {
76          "date_of_birth": "1970-06-01"
77        },
78        "citizenship": "US",
79        "identification_documents": [
80          {
81            "identification_number": "323964099",
82            "issuing_country_code": "US",
83            "type": "SOCIAL_SECURITY_NUMBER"
84          }
85        ],
86        "names": [
87          {
88            "given_name": "Jane",
89            "surname": "Doe",
90            "type": "LEGAL"
91          }
92        ],
93        "role": "DIRECTOR"
94      }
95    ],
96    "beneficial_owners": {
97      "individuals": [
98        {
99          "addresses": [
100            {
101              "address_line_1": "7703 Eastport Pkwy",
102              "admin_area_1": "NE",
103              "admin_area_2": "La Vista",
104              "country_code": "US",
105              "postal_code": "68128",
106              "type": "HOME"
107            }
108          ],
109          "birth_details": {
110            "date_of_birth": "1970-01-01"
111          },
112          "citizenship": "US",
113          "names": [
114            {
115              "given_name": "Justin",
116              "surname": "Doe",
117              "type": "LEGAL"
118            }
119          ],
120          "percentage_of_ownership": "75",
121          "identification_documents": [
122            {
123              "identification_number": "501985796",
124              "issuing_country_code": "US",
125              "type": "SOCIAL_SECURITY_NUMBER"
126            }
127          ]
128        }
129      ]
130    },
131    "declarations": [
132      {
133        "name": "TWENTY_FIVE_PERCENT_BENEFICIAL_OWNER",
134        "value": "YES"
135      }
136    ],
137    "identification_documents": [
138      {
139        "type": "EMPLOYER_IDENTIFICATION_NUMBER",
140        "identification_number": "111222333",
141        "issuing_country_code": "US"
142      }
143    ]
144  },
145  "financial_instruments": {
146    "banks": [
147      {
148        "country_code": "US",
149        "type": "CHECKING",
150        "account_number": "78868666",
151        "account_number_type": "ALL_BANKS",
152        "currency_code": "USD",
153        "routing_number": "074001048",
154        "statement_descriptor": "Testing Shopify Add Bank! Descriptor# US CNTRY",
155        "mandate": {
156          "consent_to_debit": true
157        }
158      }
159    ]
160  },
161  "agreements": [
162    {
163      "type": "TERMS_ACCEPTED",
164      "accepted_time": "2023-06-02T01:23:45Z"
165    }
166  ],
167  "attributes": [
168    {
169      "name": "SELF_CERTIFICATION",
170      "value": "true"
171    }
172  ],
173  "organization": "US_1"
174}'

Add bank account

Use the PATCH API to add a bank account to a merchant's auto-withdrawal setup. The following examples show how to add bank accounts for merchants in the US and France.

US
France

1curl --location --request PATCH ‘{{host}}/v3/customer/managed-accounts/{id}’ --header ‘Authorization: Bearer ACCESS-TOKEN’ --header 'Content-Type: application/json '
2[
3  {
4    "op": "add",
5    "path": "/financial_instruments/banks",
6    "value": [
7      {
8        "country_code": "US",
9        "account_holder_details": {
10          "name": "Mary Collins"
11        },
12        "account_number_type": "BASIC_BANK_ACCOUNT_NUMBER",
13        "account_number": "89935377",
14        "account_type": "checking",
15        "currency_code": "USD",
16        "routing_number": "082900429",
17        "bank_name": "Bank of America",
18        "statement_descriptor": "Soft desc value of merchant"
19      }
20    ]
21  }
22]

Remove bank account

Use the PATCH API to remove the bank account associated with the auto-withdrawal setup.

1curl --location --request PATCH '{{host}}/v3/customer/managed-accounts/{id}' \
2--header 'Authorization: Bearer ACCESS-TOKEN' \
3--header 'Content-Type: application/json'
4
5[
6    {
7        "op": "remove",
8        "path": "/financial_instruments/banks/@id=='BA-37VRDBLJDASQU'"
9    }
10]

Payout processing

Payouts are initiated after the end-of-day cut-off (00:00 to 23:59) in the merchant's timezone. The merchant account balance is calculated, and payment instructions are created and sent to the account.

The payouts are made on the standard ACH rails, so the amounts are deposited in the merchant's bank account in 2-4 days.

If the merchant's account has any issue, for example, it's restricted, or the bank account is inactive or not valid, the payouts are not processed.

Note that the payout attempts will continue until you deactivate the schedule.

Payout lifecycle

Scheduled payouts do not have a lifecycle and do not generate a payout reference ID. As a result, you cannot query the status of a payout using a GET API.

Notifications

Scheduled payouts do not provide notifications. Events such as configuration changes, payout processing status, and so on are not available for these payouts.

Reconciliation

PayPal provides access to specific payout reconciliation report and settlement report, enabling merchants to reconcile pay-ins with payouts.