Airwallex logo

Beneficiary Tax Statements

Copy for LLMView as Markdown

A beneficiary tax statement is an annual 1099 form (1099-NEC or 1099-K) aggregating the taxable payments made to a recipient in a tax year, together with payer and recipient information. Use these APIs to retrieve statements, file them to the IRS, and download the rendered PDF.

GET /api/v1/beneficiary_tax_statements/{id}Retrieve a Beneficiary Tax Statement
GET /api/v1/beneficiary_tax_statementsList all Beneficiary Tax Statements
POST /api/v1/beneficiary_tax_statements/{id}/submitSubmit a Beneficiary Tax Statement
POST /api/v1/beneficiary_tax_statements/{id}/downloadDownload a Beneficiary Tax Statement

Retrieve a Beneficiary Tax Statement

GET /api/v1/beneficiary_tax_statements/{id}

Retrieve the details of a specific beneficiary tax statement by its unique ID.

Scoped API key permissions
PayoutsBeneficiary Tax StatementsRead
On behalf of
Supports x-on-behalf-of header
Path parameters
idrequiredstring

Unique ID of the beneficiary tax statement.

Response body - 200 OK
created_atstring

Time when the tax statement was created, in ISO 8601 format.

external_idstring

Unique identifier of a recipient.

idstring

Unique ID of the tax statement.

payer_infoobject

Payer information.

payer_info.addressobject

A physical address used for tax reporting.

payer_info.address.address_line1string

The first line of a physical address, typically including the street number and name of the building or residence. A P.O. box is not acceptable.

payer_info.address.country_codestring

Country code (2-letter ISO 3166-1 alpha-2 country code).

payer_info.address.country_namestring

Country name.

payer_info.address.postcodestring

Postcode or zip code.

payer_info.address.statestring

Name of state.

payer_info.address.suburbstring

Name of city / suburb.

payer_info.address.address_line2string

An optional field that can be used to capture additional information about the address, such as the apartment/suite number, or floor number.

payer_info.address.state_codestring

2-letter state code.

payer_info.namestring

The person's name.

payer_info.phone_numberstring

The person's phone number.

payer_info.tax_identifierobject

Taxpayer Identification Number (TIN) of the recipient.

payer_info.tax_identifier.numberstring

The Tax Identification number.

payer_info.tax_identifier.typestring

Type of Tax Identification.

SSN

Social Security Number.

EIN

Employer Identification Number.

ITIN

Individual Taxpayer Identification Number.

QI_EIN

Qualified Intermediary Employer Identification Number.

WP_EIN

Withholding Foreign Partnership Employer Identification Number.

WT_EIN

Withholding Foreign Trust Employer Identification Number.

recipient_infoobject

Recipient information.

recipient_info.addressobject

A physical address used for tax reporting.

recipient_info.address.address_line1string

The first line of a physical address, typically including the street number and name of the building or residence. A P.O. box is not acceptable.

recipient_info.address.country_codestring

Country code (2-letter ISO 3166-1 alpha-2 country code).

recipient_info.address.country_namestring

Country name.

recipient_info.address.postcodestring

Postcode or zip code.

recipient_info.address.statestring

Name of state.

recipient_info.address.suburbstring

Name of city / suburb.

recipient_info.address.address_line2string

An optional field that can be used to capture additional information about the address, such as the apartment/suite number, or floor number.

recipient_info.address.state_codestring

2-letter state code.

recipient_info.beneficiary_tax_profile_versioninteger

The version of the tax profile used as the source of recipient information.

recipient_info.namestring

The person's name.

recipient_info.phone_numberstring

The person's phone number.

recipient_info.tax_identifierobject

Taxpayer Identification Number (TIN) of the recipient.

recipient_info.tax_identifier.numberstring

The Tax Identification number.

recipient_info.tax_identifier.typestring

Type of Tax Identification.

SSN

Social Security Number.

EIN

Employer Identification Number.

ITIN

Individual Taxpayer Identification Number.

QI_EIN

Qualified Intermediary Employer Identification Number.

WP_EIN

Withholding Foreign Partnership Employer Identification Number.

WT_EIN

Withholding Foreign Trust Employer Identification Number.

rejection_reasonstring

Reason for rejection by the IRS. Present when the statement was rejected by the IRS after filing.

statusstring

Status of the tax statement.

NOT_READY

Payer or recipient details are incomplete. The statement is not ready to be filed

FILING_NOT_APPLICABLE

Filing is not applicable (the recipient is non-US, or the taxable income is $0)

FILING_OPTIONAL

Tax statement is complete and taxable income is greater than $0 but does not meet the mandatory threshold

FILING_REQUIRED

Tax statement is complete and taxable income meets the mandatory threshold

FILING_IN_PROGRESS

The filing process has started asynchronously in the background

FILED

The statement has been filed to the IRS

ACCEPTED

The statement has been accepted by the IRS

REJECTED

The statement has been rejected by the IRS

EXPIRED

The statement has not been filed and expired after 2 years automatically

tax_yearinteger

The tax year of this statement.

total_taxable_amountnumber

Total transfer amount submitted to the IRS, in US dollars.

typestring

The tax statement form type.

1099-NEC

Form 1099-NEC, reporting nonemployee compensation

1099-K

Form 1099-K, reporting payment card and third-party network transactions

updated_atstring

Time when the tax statement was last updated, in ISO 8601 format.

Errors
Error statusDescription
400

Possible errors: invalid_argument, bad_request

404

Possible errors: not_found

GET /api/v1/beneficiary_tax_statements/{id}
$curl --request GET \
> --url 'https://api.sandbox.airwallex.com/api/v1/beneficiary_tax_statements/txs-1a2b3c4d5e6f' \
> --header 'Authorization: Bearer <token>' \
> --header 'Content-Type: application/json'
Response (200 OK)
1{
2 "id": "txs-1a2b3c4d5e6f",
3 "external_id": "recipient_98765",
4 "tax_year": 2025,
5 "type": "1099-NEC",
6 "status": "FILING_REQUIRED",
7 "payer_info": {
8 "name": "Acme Corp",
9 "address": {
10 "address_line1": "123 Main Street",
11 "address_line2": "Suite 400",
12 "suburb": "San Francisco",
13 "state": "California",
14 "state_code": "CA",
15 "postcode": "94105",
16 "country_code": "US",
17 "country_name": "United States"
18 },
19 "phone_number": "415-555-0100",
20 "tax_identifier": {
21 "type": "EIN",
22 "number": "123456789"
23 }
24 },
25 "recipient_info": {
26 "name": "Jane Doe",
27 "address": {
28 "address_line1": "456 Oak Avenue",
29 "suburb": "Austin",
30 "state": "Texas",
31 "state_code": "TX",
32 "postcode": "78701",
33 "country_code": "US",
34 "country_name": "United States"
35 },
36 "phone_number": "512-555-0199",
37 "tax_identifier": {
38 "type": "SSN",
39 "number": "987654321"
40 },
41 "beneficiary_tax_profile_version": 1
42 },
43 "total_taxable_amount": 10000,
44 "created_at": "2026-01-15T08:30:00+0000",
45 "updated_at": "2026-02-03T14:22:45+0000"
46}
Was this section helpful?

List all Beneficiary Tax Statements

GET /api/v1/beneficiary_tax_statements

Retrieve a list of beneficiary tax statements, filtered by the supplied query parameters. Results are paginated using a cursor.

Scoped API key permissions
PayoutsBeneficiary Tax StatementsRead
On behalf of
Supports x-on-behalf-of header
Query parameters
tax_yearrequiredinteger

Filter by beneficiary tax statement year.

external_idstring

Filter by the unique identifier of a recipient.

pagestring

A bookmark for use in pagination to retrieve either the next page or the previous page of results. To retrieve the next page of results, pass the value of page_after (if not null) from the response to a subsequent call. To retrieve the previous page of results, pass the value of page_before (if not null) from the response to a subsequent call.

page_sizeinteger

Number of results per page. Defaults to 100, minimum 10, maximum 200.

statusstring

Filter by beneficiary tax statement status.

NOT_READY

Payer or recipient details are incomplete. The statement is not ready to be filed

FILING_NOT_APPLICABLE

Filing is not applicable (the recipient is non-US, or the taxable income is $0)

FILING_OPTIONAL

Tax statement is complete and taxable income is greater than $0 but does not meet the mandatory threshold

FILING_REQUIRED

Tax statement is complete and taxable income meets the mandatory threshold

FILING_IN_PROGRESS

The filing process has started asynchronously in the background

FILED

The statement has been filed to the IRS

ACCEPTED

The statement has been accepted by the IRS

REJECTED

The statement has been rejected by the IRS

EXPIRED

The statement has not been filed and expired after 2 years automatically

Response body - 200 OK
itemsarray

An array of paged results.

items.external_idstring

Unique identifier of a recipient.

items.idstring

Unique ID of the tax statement.

items.statusstring

Status of the tax statement.

NOT_READY

Payer or recipient details are incomplete. The statement is not ready to be filed

FILING_NOT_APPLICABLE

Filing is not applicable (the recipient is non-US, or the taxable income is $0)

FILING_OPTIONAL

Tax statement is complete and taxable income is greater than $0 but does not meet the mandatory threshold

FILING_REQUIRED

Tax statement is complete and taxable income meets the mandatory threshold

FILING_IN_PROGRESS

The filing process has started asynchronously in the background

FILED

The statement has been filed to the IRS

ACCEPTED

The statement has been accepted by the IRS

REJECTED

The statement has been rejected by the IRS

EXPIRED

The statement has not been filed and expired after 2 years automatically

items.tax_yearinteger

The tax year of this statement.

items.typestring

The tax statement form type.

1099-NEC

Form 1099-NEC, reporting nonemployee compensation

1099-K

Form 1099-K, reporting payment card and third-party network transactions

items.created_atstring

Time when the tax statement was created, in ISO 8601 format.

items.payer_infoobject

Payer information.

items.payer_info.addressobject

A physical address used for tax reporting.

items.payer_info.address.address_line1string

The first line of a physical address, typically including the street number and name of the building or residence. A P.O. box is not acceptable.

items.payer_info.address.country_codestring

Country code (2-letter ISO 3166-1 alpha-2 country code).

items.payer_info.address.country_namestring

Country name.

items.payer_info.address.postcodestring

Postcode or zip code.

items.payer_info.address.statestring

Name of state.

items.payer_info.address.suburbstring

Name of city / suburb.

items.payer_info.address.address_line2string

An optional field that can be used to capture additional information about the address, such as the apartment/suite number, or floor number.

items.payer_info.address.state_codestring

2-letter state code.

items.payer_info.namestring

The person's name.

items.payer_info.phone_numberstring

The person's phone number.

items.payer_info.tax_identifierobject

Taxpayer Identification Number (TIN) of the recipient.

items.payer_info.tax_identifier.numberstring

The Tax Identification number.

items.payer_info.tax_identifier.typestring

Type of Tax Identification.

SSN

Social Security Number.

EIN

Employer Identification Number.

ITIN

Individual Taxpayer Identification Number.

QI_EIN

Qualified Intermediary Employer Identification Number.

WP_EIN

Withholding Foreign Partnership Employer Identification Number.

WT_EIN

Withholding Foreign Trust Employer Identification Number.

items.recipient_infoobject

Recipient information.

items.recipient_info.addressobject

A physical address used for tax reporting.

items.recipient_info.address.address_line1string

The first line of a physical address, typically including the street number and name of the building or residence. A P.O. box is not acceptable.

items.recipient_info.address.country_codestring

Country code (2-letter ISO 3166-1 alpha-2 country code).

items.recipient_info.address.country_namestring

Country name.

items.recipient_info.address.postcodestring

Postcode or zip code.

items.recipient_info.address.statestring

Name of state.

items.recipient_info.address.suburbstring

Name of city / suburb.

items.recipient_info.address.address_line2string

An optional field that can be used to capture additional information about the address, such as the apartment/suite number, or floor number.

items.recipient_info.address.state_codestring

2-letter state code.

items.recipient_info.beneficiary_tax_profile_versioninteger

The version of the tax profile used as the source of recipient information.

items.recipient_info.namestring

The person's name.

items.recipient_info.phone_numberstring

The person's phone number.

items.recipient_info.tax_identifierobject

Taxpayer Identification Number (TIN) of the recipient.

items.recipient_info.tax_identifier.numberstring

The Tax Identification number.

items.recipient_info.tax_identifier.typestring

Type of Tax Identification.

SSN

Social Security Number.

EIN

Employer Identification Number.

ITIN

Individual Taxpayer Identification Number.

QI_EIN

Qualified Intermediary Employer Identification Number.

WP_EIN

Withholding Foreign Partnership Employer Identification Number.

WT_EIN

Withholding Foreign Trust Employer Identification Number.

items.rejection_reasonstring

Reason for rejection by the IRS. Present when the statement was rejected by the IRS after filing.

items.total_taxable_amountnumber

Total transfer amount submitted to the IRS, in US dollars.

items.updated_atstring

Time when the tax statement was last updated, in ISO 8601 format.

page_afterstring

The cursor for the next page of results. Pass this value as page in a subsequent request. null if there are no more results.

page_beforestring

The cursor for the previous page of results. Pass this value as page in a subsequent request. null if there are no previous results.

Errors
Error statusDescription
400

Possible errors: invalid_argument, bad_request

GET /api/v1/beneficiary_tax_statements
$curl --request GET \
> --url 'https://api.sandbox.airwallex.com/api/v1/beneficiary_tax_statements' \
> --header 'Authorization: Bearer <token>' \
> --header 'Content-Type: application/json'
Response (200 OK)
1{
2 "items": [
3 {
4 "id": "txs-1a2b3c4d5e6f",
5 "external_id": "recipient_98765",
6 "tax_year": 2025,
7 "type": "1099-NEC",
8 "status": "FILING_REQUIRED",
9 "recipient_info": {
10 "name": "Jane Doe",
11 "beneficiary_tax_profile_version": 1
12 },
13 "total_taxable_amount": 10000,
14 "created_at": "2026-01-15T08:30:00+0000",
15 "updated_at": "2026-02-03T14:22:45+0000"
16 }
17 ],
18 "page_before": "<string>",
19 "page_after": "eyJwYWdlIjogMn0"
20}
Was this section helpful?

Submit a Beneficiary Tax Statement

POST /api/v1/beneficiary_tax_statements/{id}/submit

Submit the beneficiary tax statement to the IRS. The response contains the tax statement and its current filing status. This endpoint does not require a request body.

Scoped API key permissions
PayoutsBeneficiary Tax StatementsWrite
On behalf of
Supports x-on-behalf-of header
Path parameters
idrequiredstring

Unique ID of the tax statement to file.

Response body - 200 OK
created_atstring

Time when the tax statement was created, in ISO 8601 format.

external_idstring

Unique identifier of a recipient.

idstring

Unique ID of the tax statement.

payer_infoobject

Payer information.

payer_info.addressobject

A physical address used for tax reporting.

payer_info.address.address_line1string

The first line of a physical address, typically including the street number and name of the building or residence. A P.O. box is not acceptable.

payer_info.address.country_codestring

Country code (2-letter ISO 3166-1 alpha-2 country code).

payer_info.address.country_namestring

Country name.

payer_info.address.postcodestring

Postcode or zip code.

payer_info.address.statestring

Name of state.

payer_info.address.suburbstring

Name of city / suburb.

payer_info.address.address_line2string

An optional field that can be used to capture additional information about the address, such as the apartment/suite number, or floor number.

payer_info.address.state_codestring

2-letter state code.

payer_info.namestring

The person's name.

payer_info.phone_numberstring

The person's phone number.

payer_info.tax_identifierobject

Taxpayer Identification Number (TIN) of the recipient.

payer_info.tax_identifier.numberstring

The Tax Identification number.

payer_info.tax_identifier.typestring

Type of Tax Identification.

SSN

Social Security Number.

EIN

Employer Identification Number.

ITIN

Individual Taxpayer Identification Number.

QI_EIN

Qualified Intermediary Employer Identification Number.

WP_EIN

Withholding Foreign Partnership Employer Identification Number.

WT_EIN

Withholding Foreign Trust Employer Identification Number.

recipient_infoobject

Recipient information.

recipient_info.addressobject

A physical address used for tax reporting.

recipient_info.address.address_line1string

The first line of a physical address, typically including the street number and name of the building or residence. A P.O. box is not acceptable.

recipient_info.address.country_codestring

Country code (2-letter ISO 3166-1 alpha-2 country code).

recipient_info.address.country_namestring

Country name.

recipient_info.address.postcodestring

Postcode or zip code.

recipient_info.address.statestring

Name of state.

recipient_info.address.suburbstring

Name of city / suburb.

recipient_info.address.address_line2string

An optional field that can be used to capture additional information about the address, such as the apartment/suite number, or floor number.

recipient_info.address.state_codestring

2-letter state code.

recipient_info.beneficiary_tax_profile_versioninteger

The version of the tax profile used as the source of recipient information.

recipient_info.namestring

The person's name.

recipient_info.phone_numberstring

The person's phone number.

recipient_info.tax_identifierobject

Taxpayer Identification Number (TIN) of the recipient.

recipient_info.tax_identifier.numberstring

The Tax Identification number.

recipient_info.tax_identifier.typestring

Type of Tax Identification.

SSN

Social Security Number.

EIN

Employer Identification Number.

ITIN

Individual Taxpayer Identification Number.

QI_EIN

Qualified Intermediary Employer Identification Number.

WP_EIN

Withholding Foreign Partnership Employer Identification Number.

WT_EIN

Withholding Foreign Trust Employer Identification Number.

rejection_reasonstring

Reason for rejection by the IRS. Present when the statement was rejected by the IRS after filing.

statusstring

Status of the tax statement.

NOT_READY

Payer or recipient details are incomplete. The statement is not ready to be filed

FILING_NOT_APPLICABLE

Filing is not applicable (the recipient is non-US, or the taxable income is $0)

FILING_OPTIONAL

Tax statement is complete and taxable income is greater than $0 but does not meet the mandatory threshold

FILING_REQUIRED

Tax statement is complete and taxable income meets the mandatory threshold

FILING_IN_PROGRESS

The filing process has started asynchronously in the background

FILED

The statement has been filed to the IRS

ACCEPTED

The statement has been accepted by the IRS

REJECTED

The statement has been rejected by the IRS

EXPIRED

The statement has not been filed and expired after 2 years automatically

tax_yearinteger

The tax year of this statement.

total_taxable_amountnumber

Total transfer amount submitted to the IRS, in US dollars.

typestring

The tax statement form type.

1099-NEC

Form 1099-NEC, reporting nonemployee compensation

1099-K

Form 1099-K, reporting payment card and third-party network transactions

updated_atstring

Time when the tax statement was last updated, in ISO 8601 format.

Errors
Error statusDescription
400

Possible errors: invalid_argument, bad_request, operation_failed

404

Possible errors: not_found

POST /api/v1/beneficiary_tax_statements/{id}/submit
$curl --request POST \
> --url 'https://api.sandbox.airwallex.com/api/v1/beneficiary_tax_statements/txs-1a2b3c4d5e6f/submit' \
> --header 'Authorization: Bearer <token>' \
> --header 'Content-Type: application/json'
Response (200 OK)
1{
2 "id": "txs-1a2b3c4d5e6f",
3 "external_id": "recipient_98765",
4 "tax_year": 2025,
5 "type": "1099-NEC",
6 "status": "FILING_IN_PROGRESS",
7 "recipient_info": {
8 "name": "Jane Doe",
9 "beneficiary_tax_profile_version": 1
10 },
11 "total_taxable_amount": 10000
12}
Was this section helpful?

Download a Beneficiary Tax Statement

POST /api/v1/beneficiary_tax_statements/{id}/download

Generate the PDF of a beneficiary tax statement (the rendered 1099 form).

Scoped API key permissions
PayoutsBeneficiary Tax StatementsRead
On behalf of
Supports x-on-behalf-of header
Path parameters
idrequiredstring

Unique ID of the tax statement.

Response body - 200 OK
download_urlstring

URL that can be used to retrieve the file. This URL expires shortly after it is generated.

expires_atstring

Download URL expiry timestamp, in ISO 8601 format.

Errors
Error statusDescription
400

Possible errors: invalid_argument, bad_request

404

Possible errors: not_found

POST /api/v1/beneficiary_tax_statements/{id}/download
$curl --request POST \
> --url 'https://api.sandbox.airwallex.com/api/v1/beneficiary_tax_statements/txs-1a2b3c4d5e6f/download' \
> --header 'Authorization: Bearer <token>'
Response (200 OK)
1{
2 "download_url": "https://api-downloads.airwallex.com/beneficiary_tax_statements/txs-1a2b3c4d5e6f.pdf?signature=1a2b3c4d5e6f7a8b9c0d",
3 "expires_at": "2026-06-10T08:35:00+0000"
4}
Was this section helpful?