WEpayments' Payout API (1.3)

Download OpenAPI specification:Download

Integration Team: integration@wepayments.com.br

Use this API to access and manage your WEpayments payment's account data.

Authentication

Authorization

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer

Overview

With the payout API, you are able to efficiently manage your deposits, payments, and balances:
Payments: Handle all transactions destined for your beneficiaries.
Deposits: Manage the funds within your wallet.
Transactions: Access comprehensive data from your account statement.

Payment

Payments supports webhook notifications, to receive notifications please provide a valid URL in the notification_url field.

Possible charge status Payment

status_code	status	explanation
`7`	AWAITING	The first status. If you stay in this status for more than 1 minute, it means that no balance in your account to make the payment.
`1`	RECEIVED	Payment received and stored in our database.
`2`	PROCESSING	Payment sent for processing.
`5`	INREVIEW	Payment sent to our team for review.
`8`	PROCESSED	Payments sent for processing and waiting confirmation from processor.
`3`	PAID	Payment made with success.
`4`	REJECTED	Payment rejected by the bank (only TED).
`6`	CANCELED	Payment canceled by Merchant (TED or PIX) or Payment rejected by the bank (Only PIX).
`11`	INVALID_DATA_INPUT	Data provided invalid or insuficcient (only available under client request).

Payments in final statuses (PAID, CANCELED,REJECTED) can no longer be updated.

Add a new payment

Use this endpoint to send payment instructions to WEpayments

Authorizations:

Authorization

Request Body schema: application/json

Payment object to be added

merchant_id	number Merchant_id of the account creating the payment. The Merchant_id will be different for sandbox and production environment. Is mandatory if there is more than one account under your umbrella (sellers).
source_currency	string Source currency.
amount required	number <double> Float with the amount in BRL to be sent.
custom_code required	string Your identification number, it must be unique on our database.
notification_url	string We will send you a HTTP POST with a `Notification` Object when the transfer status changes.
required	object (Beneficiary) Details of the final beneficiary (who will receive the payment)
	object (Remitter) Mandatory for the remittance model. Payments from individuals to individuals.
legal_entity_name	string The name of the payout originator. Mandatory when payment is being made by another company other than Merchant. Example: Merchants who are PSP and/or Payment Gateway.
website	string Website of the payout originator. Mandatory when payment is being made by another company other than Merchant. Example: Merchants who are PSP and/or Payment Gateway.
instant_payment required	integer [ 0 .. 1 ] Enum: 0 1 Method of payment: 1 -> Pix (Instant payment, available every day 24 hours a day); 0 -> TED (Payment subject to banking window, available on useful days during banking hours).
receipt_message	string <= 140 characters The message that will be rendered in the payment's receipt.
description	string <= 140 characters This field content will be sent along with the payment to the beneficiary, available only for instant payments.
	Array of objects (RegisteredAccounts) [ items ] Registered accounts that are allowed to make the Payment, if the pix key is for an account that is not on this list, the payment will be rejected.

Responses

Callbacks

Request samples

Payload

Content type

application/json

Example

{"amount": 100,
"custom_code": "YOUR-CODE1234",
"notification_url": "https://client.callback.com/notify-payout",
"beneficiary": {"name": "The beneficiary name",
"pix_key": "mypix@gmail.com",
"document": "34960826312",
"document_type": "cpf"
},
"instant_payment": 1
}

Response samples

201
400
403

Content type

application/json

Example

{"id": 114979,
"origin_payment_id": null,
"amount": "R$ 100,00",
"source_currency": "BRL",
"source_amount": null,
"custom_code": "SE2024-019",
"authentication_code": null,
"rejection_description": "",
"notification_url": "https://client.callback.com/notify-payout",
"status": {"id": 7,
"name": "Awaiting"
},
"paid_at": null,
"created_at": "2024-03-12 17:12:17",
"updated_at": "2024-03-12 17:12:17",
"description": null,
"currency": "BRL",
"beneficiary": {"name": "The Beneficiary Name",
"document_type": "cpf",
"email": null,
"document": "34960826312",
"birthdate": null,
"city": null,
"postal_code": null,
"province_code": null,
"address": null,
"pix_key": "mypix@gmail.com",
"bank_branch": null,
"bank_branch_digit": null,
"account": null,
"account_digit": null,
"account_type": "",
"bank_code": null,
"ispb": null,
"bank_name": null
},
"payment_type": "P",
"merchant": {"id": 2689,
"name": "Merchant Name",
"type": "u"
},
"exchange_rate": null,
"locked": null,
"file_code": null
}

Callback payload samples

Callback

POST: All payments webhooks are signed with an sha256 ha

Content type

application/json

{"custom_code": "YOURAPPCODE",
"property": "Deposit",
"property_id": 0,
"amount": 0,
"currency": "string",
"batch_code": "string",
"date": "2019-01-01 01:00:00",
"description": "string",
"status_id": 0,
"status": "Received",
"beneficiary_bank_data": {"bank_branch": "string",
"account": "string",
"account_digit": "string",
"account_type": "string",
"bank_code": "string",
"ispb": "string",
"bank_name": "string"
},
"reason_canceled": {"id": "string",
"name": "string"
}
}

A paginated, filterable and sortable list of payouts

List your bank transfer payments.

Use filters and pagination to navigate in the database.

Payments have two types: Eletronic transfer and Instant Payment

Eletronic transfer are processed only in business days. Instant payments can be processed at 24/7.

Authorizations:

Authorization

query Parameters

per_page	integer >= 0 The number of items that will be displayed per page on paginated lists.
page	integer >= 0 The current page that will be displayed on paginated lists.
order_by	string Default: "id" Enum: "id" "custom_code" "merchant.name" "amount" "beneficiary.name" "processor.name" "created_at" "paid_at" "status.name" define the ordering of the query
sort	string Default: "desc" Enum: "asc" "desc" Define the sort order, ascendant or descendant
id	string
beneficiary_name	string the name of a single or multiple beneficiaries separated by comma.
merchant_id	string
beneficiary_document	string
processor_id	string
status_id	string
bank_name	string
custom_code	string
amount	number
payout_type	string Enum: "u" "r"
remitter_country	string Example: remitter_country=USA Filter records by country of remitter, in ISO3 format
created_after	string
created_before	string
updated_after	string
updated_before	string

Responses

Response samples

200

Content type

application/json

[{"id": 111111,
"amount": 1000,
"source_currency": "USD",
"source_amount": 250,
"custom_code": "YOURAPPCODE",
"authentication_code": "8132F296ECE9271E97A776777",
"payment_type": "T",
"rejection_description": "Rejected by bank",
"notification_url": "https://your.endpoint.to.update",
"beneficiary": {"name": "The Name",
"pix_key": "userpixkey@user.com",
"ispb": "60746948",
"bank_branch": "0000",
"bank_branch_digit": "1",
"account_digit": "1",
"account_type": "CHECKING",
"account": "1030000",
"document": "12533009091",
"document_type": "cpf",
"birthdate": "1996-07-08",
"phone": "5541987456321",
"city": "Curitiba",
"postal_code": "80200-100",
"province_code": "PR",
"address": "Rua a Número 10"
},
"remitter": {"name": "The remitter's name",
"birthdate": "1996-01-01",
"country": "USA"
},
"status": {"id": 1,
"name": "Received"
},
"substatus": {"id": 1,
"name": "Amount limit by payment",
"description": "Reached BRL - 32K limit per payment"
},
"paid_at": "2020-01-01 23:59:59",
"created_at": "2020-01-01 23:59:59",
"updated_at": "2020-01-01 23:59:59",
"description": "Payment description",
"currency": "BRL"
}
]

Add a payment batch

Similar to POST /payments.
With this method you can send a payment batch, the payment batch request cannot have more than 20000 payments lenght or 20MB size.'

Authorizations:

Authorization

Request Body schema: application/json

notification_url	string The notitifation url to send updates
required	Array of PaymentWithPixKeyInsideBatch (object) or PaymentWithBankDetailsInsideBatch (object)[ items ]

Responses

Callbacks

Request samples

Payload

Content type

application/json

{"notification_url": "https://your.endpoint",
"payments": [{"amount": 0.01,
"custom_code": "unique-code1",
"beneficiary": {"name": "The Name",
"pix_key": "userpixkey@user.com",
"document": "12533009091",
"document_type": "cpf"
},
"legal_entity_name": "The entity that owns the payment",
"website": "The entity that owns the payment website",
"instant_payment": 1
},
{"amount": 0,
"custom_code": "unique-code2",
"beneficiary": {"name": "The Name",
"bank_code": "147",
"ispb": "60746948",
"bank_branch": "0000",
"bank_branch_digit": "1",
"account": "1030000",
"account_digit": "1",
"account_type": "CHECKING",
"document": "12533009091",
"document_type": "cpf"
},
"legal_entity_name": "The entity that owns the payment",
"website": "the entity that owns the payment website",
"instant_payment": 1
}
]
}

Response samples

201

Content type

application/json

{"count": 0,
"total_amount": 0,
"batch_code": "string"
}

Callback payload samples

Callback

Content type

application/json

{"custom_code": "YOURAPPCODE",
"property": "Deposit",
"property_id": 0,
"amount": 0,
"currency": "string",
"batch_code": "string",
"date": "2019-01-01 01:00:00",
"description": "string",
"status_id": 0,
"status": "Received",
"beneficiary_bank_data": {"bank_branch": "string",
"account": "string",
"account_digit": "string",
"account_type": "string",
"bank_code": "string",
"ispb": "string",
"bank_name": "string"
},
"reason_canceled": {"id": "string",
"name": "string"
}
}

Export filtered payments receipts in .zip

Authorizations:

Authorization

query Parameters

order_by	string Default: "payment.id" Enum: "payment.id" "custom_code" "merchant.name" "amount" "beneficiary.name" "processor.name" "paid_at" "status.name" define the ordering of the query
sort	string Default: "desc" Enum: "asc" "desc" Define the sort order, ascendant or descendant
id	string
beneficiary_name	string the name of a single or multiple beneficiaries separated by comma.
merchant_id	string
beneficiary_document	string
processor_id	string
status_id	integer Default: 3 Value: 3
created_after	string
created_before	string

Request Body schema: text/plain

A link to download the .zip file

object

Responses

Request samples

Payload

Content type

text/plain

https://export-payouts-data.s3.amazonaws.com/temporaryfilename.zip

Response samples

200

Content type

text/plain

https://url-to-download/file.zip

Returns a payment by ID.

Get a Payment object by its ID

Authorizations:

Authorization

path Parameters

paymentID

required

integer

The ID of the payment to return.

Responses

Response samples

200

Content type

application/json

{"id": 111111,
"amount": 1000,
"source_currency": "USD",
"source_amount": 250,
"custom_code": "YOURAPPCODE",
"authentication_code": "8132F296ECE9271E97A776777",
"payment_type": "T",
"rejection_description": "Rejected by bank",
"notification_url": "https://your.endpoint.to.update",
"beneficiary": {"name": "The Name",
"pix_key": "userpixkey@user.com",
"ispb": "60746948",
"bank_branch": "0000",
"bank_branch_digit": "1",
"account_digit": "1",
"account_type": "CHECKING",
"account": "1030000",
"document": "12533009091",
"document_type": "cpf",
"birthdate": "1996-07-08",
"phone": "5541987456321",
"city": "Curitiba",
"postal_code": "80200-100",
"province_code": "PR",
"address": "Rua a Número 10"
},
"remitter": {"name": "The remitter's name",
"birthdate": "1996-01-01",
"country": "USA"
},
"status": {"id": 1,
"name": "Received"
},
"substatus": {"id": 1,
"name": "Amount limit by payment",
"description": "Reached BRL - 32K limit per payment"
},
"paid_at": "2020-01-01 23:59:59",
"created_at": "2020-01-01 23:59:59",
"updated_at": "2020-01-01 23:59:59",
"description": "Payment description",
"currency": "BRL"
}

Cancels a payment by ID.

Payouts can only be canceled on Received status only. If you need to cancel a payment in another status it is necessary to send an email to WePayout for the evaluation if a cancelation is possible or not.

Authorizations:

Authorization

path Parameters

paymentID

required

integer

The ID of the payment to be deleted.

Responses

Response samples

200

Content type

application/json

{"id": 111111,
"amount": 1000,
"source_currency": "USD",
"source_amount": 250,
"custom_code": "YOURAPPCODE",
"authentication_code": "8132F296ECE9271E97A776777",
"payment_type": "T",
"rejection_description": "Rejected by bank",
"notification_url": "https://your.endpoint.to.update",
"beneficiary": {"name": "The Name",
"pix_key": "userpixkey@user.com",
"ispb": "60746948",
"bank_branch": "0000",
"bank_branch_digit": "1",
"account_digit": "1",
"account_type": "CHECKING",
"account": "1030000",
"document": "12533009091",
"document_type": "cpf",
"birthdate": "1996-07-08",
"phone": "5541987456321",
"city": "Curitiba",
"postal_code": "80200-100",
"province_code": "PR",
"address": "Rua a Número 10"
},
"remitter": {"name": "The remitter's name",
"birthdate": "1996-01-01",
"country": "USA"
},
"status": {"id": 1,
"name": "Received"
},
"substatus": {"id": 1,
"name": "Amount limit by payment",
"description": "Reached BRL - 32K limit per payment"
},
"paid_at": "2020-01-01 23:59:59",
"created_at": "2020-01-01 23:59:59",
"updated_at": "2020-01-01 23:59:59",
"description": "Payment description",
"currency": "BRL"
}

Returns a payment by CustomCode.

Return the payment object using your custom code

Authorizations:

Authorization

path Parameters

customCode

required

integer

The CustomCode of the payment to return.

Responses

Response samples

200

Content type

application/json

{"id": 111111,
"amount": 1000,
"source_currency": "USD",
"source_amount": 250,
"custom_code": "YOURAPPCODE",
"authentication_code": "8132F296ECE9271E97A776777",
"payment_type": "T",
"rejection_description": "Rejected by bank",
"notification_url": "https://your.endpoint.to.update",
"beneficiary": {"name": "The Name",
"pix_key": "userpixkey@user.com",
"ispb": "60746948",
"bank_branch": "0000",
"bank_branch_digit": "1",
"account_digit": "1",
"account_type": "CHECKING",
"account": "1030000",
"document": "12533009091",
"document_type": "cpf",
"birthdate": "1996-07-08",
"phone": "5541987456321",
"city": "Curitiba",
"postal_code": "80200-100",
"province_code": "PR",
"address": "Rua a Número 10"
},
"remitter": {"name": "The remitter's name",
"birthdate": "1996-01-01",
"country": "USA"
},
"status": {"id": 1,
"name": "Received"
},
"substatus": {"id": 1,
"name": "Amount limit by payment",
"description": "Reached BRL - 32K limit per payment"
},
"paid_at": "2020-01-01 23:59:59",
"created_at": "2020-01-01 23:59:59",
"updated_at": "2020-01-01 23:59:59",
"description": "Payment description",
"currency": "BRL"
}

Returns the receipt of a payment.

Get the receipt of the payment in HTML format

Authorizations:

Authorization

path Parameters

paymentID

required

integer

The ID of the payment to return.

Responses

Deposit

Manage your funding deposits.
Deposits can have two types: FEE or PAYOUT.
FEE deposits are used to fund your fee wallet.
PAYOUT deposits are used to fund your payout wallet. Deposits also supports webhook notifications, to receive notifications please provide a valid URL in the notification_url field.
Deposits can have the following statuses:

CREATED - Deposit created at WePayment's platform
CONFIRMED - Deposit received by the Broker but isn't credited yet at a BRL account.
CANCELED - Deposit canceled by the Merchant
REJECTED - Deposit rejected by the bank, Broker or WePayments
IN_REVIEW - Deposit with some divergence which is waiting bank, WePayments or Merchant analyzes.
CREDITED - Deposit credited at BRL account and at Merchant account

List deposits with given filter

Get the list of Deposits that you registered in WePayments. You can use filters and pagination to navigate in the database.

Authorizations:

Authorization

query Parameters

per_page	integer >= 0 The number of items that will be displayed per page on paginated lists.
page	integer >= 0 The current page that will be displayed on paginated lists.
order_by	string Default: "deposit.id" Enum: "deposit.id" "merchant.name" "currency.name" "sender_name" "amount" "converted_amount" "date" "status" "type" "deposit.created_at" define the ordering of the query
sort	string Default: "desc" Enum: "asc" "desc" Define the sort order, ascendant or descendant
merchant_name	string Name of a single or multiple merchants separated by comma
created_after	string
created_before	string
updated_after	string
updated_before	string
merchant_id	string
currency.name	string The name of the currency
id	string WPO ID
status_id	string single or multiple (separated by comma)

Responses

Response samples

200

Content type

application/json

[{"id": 1111111,
"status": 0,
"amount": 1000,
"sender_name": "Your company's name",
"notes": "Deposit identification or information that should be considerated",
"currency": "BRL",
"type": "FEE",
"notification_url": "https://your.endpoint.to.update",
"date": "2019-01-01",
"updated_at": "2022-09-30"
}
]

Add a new deposit

Deposits are used to register and track the funds that you send to WePayments.

When WePayments receives the deposit in foreign currency it will change the deposit status to Confirmed.
When the amount received is exchanged to local currency and the credit is received at WePayment's account, the deposit status will change to Credited and the value amount will be credited at Merchant's account.

Authorizations:

Authorization

Request Body schema: application/json

DepositRequest object to be added

amount required	number
sender_name required	string The name of the money sender
notes required	string Your deposit notes
currency required	string Enum: "BRL" "USD" "EUR" The value must be BRL, USD or EUR
type required	string Enum: "FEE" "PAYOUTS" The value must be FEE or PAYOUTS
notification_url	string We will send you a HTTP POST with a Notification Object when deposit status changes
date required	string Date refers to the date the deposit was sent from your bank account. It is important to inform the correct deposit date to WePayments be able to follow up the order with the Broker.

Responses

Callbacks

Request samples

Payload

Content type

application/json

{"amount": 1000,
"sender_name": "Your company's name",
"notes": "Deposit identification or information that should be considerated",
"currency": "BRL",
"type": "FEE",
"notification_url": "https://your.endpoint.to.update",
"date": "2019-01-01"
}

Response samples

201

Content type

application/json

{"id": 1111111,
"status": 0,
"amount": 1000,
"sender_name": "Your company's name",
"notes": "Deposit identification or information that should be considerated",
"currency": "BRL",
"type": "FEE",
"notification_url": "https://your.endpoint.to.update",
"date": "2019-01-01",
"updated_at": "2022-09-30"
}

Callback payload samples

Callback

POST: All payments webhooks are signed with an sha256 ha

Content type

application/json

{"custom_code": "YOURAPPCODE",
"property": "Deposit",
"property_id": 0,
"amount": 0,
"currency": "string",
"batch_code": "string",
"date": "2019-01-01 01:00:00",
"description": "string",
"status_id": 0,
"status": "Received",
"beneficiary_bank_data": {"bank_branch": "string",
"account": "string",
"account_digit": "string",
"account_type": "string",
"bank_code": "string",
"ispb": "string",
"bank_name": "string"
},
"reason_canceled": {"id": "string",
"name": "string"
}
}

Merchant

You can have many merchants in your account, to get information about the merchants you have access use the methods provided below:

Get a list of all available merchants

Merchants are the accounts that you have at WePayments.

Use this endpoint to navigate and filter them.

Authorizations:

Authorization

query Parameters

per_page	integer >= 0 The number of items that will be displayed per page on paginated lists.
page	integer >= 0 The current page that will be displayed on paginated lists.
order_by	string Default: "payment.id" Enum: "payment.id" "custom_code" "merchant.name" "amount" "beneficiary.name" "processor.name" "paid_at" "status.name" define the ordering of the query
sort	string Default: "desc" Enum: "asc" "desc" Define the sort order, ascendant or descendant
id	string
franchise_name	string the name of a single or multiple franchises separated by comma.
name	string the name of a single or multiple merchants separated by comma.
type	string a single or multiple types of merchant separated by comma.
legal_name	string the legal name of a single or multiple merchants separated by comma.
legal_entity_number	string the legal entity number of a single or multiple merchants separated by comma.
city	string single or multiple separated by comma.
state	string single or multiple separated by comma.
country	string single or multiple separated by comma.
fee	string single or multiple separated by comma.
exchange_rate	string single or multiple separated by comma.
created_after	string
created_before	string

Responses

Response samples

200

Content type

application/json

[{"id": 1,
"name": "Lorem Ipsum",
"type": "U",
"legal_name": "Legal Name",
"legal_entity_number": "74027713000185",
"city": "CITY",
"state": "STATE",
"country": "COUNTRY",
"logo": "path/to/logo.jpeg",
"fee": 8.88,
"exchange_rate": 2.34
}
]

Get your balance

Get the balance of some merchant.

If you have only one merchant registered you don't need to pass the merchant_id query string param.

Authorizations:

Authorization

query Parameters

merchant_id

integer

The ID of the merchant, it's required for users that has access to more than one merchant

Responses

Response samples

200

Content type

application/json

{"feeBalance": 100.99,
"payoutBalance": 1000.1,
"payoutAvailableBalance": 1000.1,
"feeAvailableBalance": 1000.1
}

Transactions

Transactions are stored in your wallet.
Each transaction has an operation_type wich can be CREDIT or DEBIT.
Transactions also impact specific wallets, this information is available in the balance_type field, wich can be FEE or PAYOUT.

A paginated, filterable and sortable list of transactions

List all transactions in the database.

Use this endpoint to paginate, filter and navigate in the database.

Authorizations:

Authorization

query Parameters

per_page	integer >= 0 The number of items that will be displayed per page on paginated lists.
page	integer >= 0 The current page that will be displayed on paginated lists.
order_by	string Default: "transaction.id" Enum: "transaction.id" "merchant.name" "operation_type" "balance_type" "description" "amount" "available_balance" "balance" "transaction.created_at" define the ordering of the query
sort	string Default: "desc" Enum: "asc" "desc" Define the sort order, ascendant or descendant
id	string
merchant_id	string
source	string Enum: "payment" "deposit" "merchant_note" The entity that generate the transaction, can be Payment, Deposit or MerchantNote
operation_type	string Enum: "D" "C" Use `D` for Debit and `C` for Credit
balance_type	string Enum: "F" "P" `F` for Fee, `P` for Payouts
created_after	string
created_before	string

Responses

Response samples

200

Content type

application/json

[{"id": 1,
"amount": 1,
"impact_balance": "Balance",
"description": "Payout Invoice: 10",
"balance_type": "Fee",
"operation_type": "Debit",
"created_at": "2020-01-01 18:00:00",
"currency": {"id": 1,
"name": "Dollars",
"code": "USD",
"symbol": "$"
},
"merchant": {"id": 1,
"name": "Lorem Ipsum",
"type": "U",
"legal_name": "Legal Name",
"legal_entity_number": "74027713000185",
"city": "CITY",
"state": "STATE",
"country": "COUNTRY",
"logo": "path/to/logo.jpeg",
"fee": 8.88,
"exchange_rate": 2.34
}
}
]

Bank

List available banks that you can make payments to.

A paginated, filterable and sortable list of institutions

Return the list of banks available

Authorizations:

Authorization

query Parameters

per_page	integer >= 0 The number of items that will be displayed per page on paginated lists.
page	integer >= 0 The current page that will be displayed on paginated lists.
order_by	string Default: "bank.id" Enum: "bank.id" "code" "name" "document_name" "logo" "created_at" "updated_at" define the ordering of the query
sort	string Default: "desc" Enum: "asc" "desc" Define the sort order, ascendant or descendant
id	string
code	string single or multiple separated by comma.
name	string single or multiple separated by comma.
document_name	string single or multiple separated by comma.
created_before	string
created_after	string
updated_before	string
updated_after	string
ispb_authorized	boolean To return only banks that have an authorized ISPB

Responses

Response samples

200

Content type

application/json

[{"code": "string",
"name": "string",
"logo": "string",
"id": 0,
"ispb": "string"
}
]

compliance

Consult CPFs

Consult total amount processed by CPF along last 365 days

In the case of merchant type remittance, only payments in paid status.

Usual merchant case, only payments in paid and "intermediate" status, except rejected and cancelled.

Authorizations:

Authorization

query Parameters

cpfs

required

string

One cpf or list of cpfs split by comma

Responses

Response samples

200

Content type

application/json

[{"merchant": "string",
"merchant_id": 0,
"amount": 0,
"document": "string",
"type": "string"
}
]