# Onboarding Documents Integration Source: https://docs.wepayout.co/account/onboarding-documents-flow End-to-end guide to integrate the document-based onboarding flow: create the solicitation, receive the required documents by webhook, upload them, track the review, and finish through signature (national) or bank channel (cross-border). > [!NOTE] > > This flow is rolled out **per merchant** through a feature flag — **off by default**. It only applies when the company is created with a **segment**. > > Merchants without the flag enabled continue on the legacy onboarding flow (which goes through `due_diligence_review`). ## Overview In the document-based onboarding, WEpayments tells your integration **exactly which documents** the company must send — resolved from its **segment** and **modality** (national / cross-border). You receive that list through the onboarding webhook, upload the files, and the solicitation advances automatically to review once every **required** document is sent. After compliance approves the documents, the flow **branches by modality** (derived from the company address country — see [Modality](#modality-national-vs-cross-border)): * **National** — the legal representatives sign the contract, then the account is created. * **Cross-border** — WEpayments opens the bank channel, then the account is created. No signature step. | Step | What you do | Endpoint / channel | | - | - | - | | 1. Register the webhook | Subscribe to onboarding status updates **before** opening the solicitation | [`POST /v2/register/webhooks`](/api-reference/account/webhook/webhook-setup) | | 2. Create the solicitation | Open the corporate account **with a `segment`** | [`POST /v2/register/companies`](/api-reference/account/create) | | 3. Receive the required documents | Read the `documents` list delivered when the status becomes `pending_documents` | [Onboarding webhook](/api-reference/account/webhook/onboarding-documents) | | 4. Upload the documents | Send each file by its `tag` | [`POST /v2/register/companies/{uuid}/documents`](/api-reference/account/documents/upload-document) | | 5. Track the review | Read the current state and decision history of each document | [`GET /v2/register/companies/{uuid}/documents`](/api-reference/account/documents/list-documents) | | 6. Sign the contract *(national only)* | Route each representative to their signing link | [`GET /v2/register/companies/{uuid}/signature/link`](/api-reference/account/signature/signature-link) | > [!NOTE] > > The compliance review (approve / reject), the bank channel opening (cross-border) and the account creation are performed **internally** by WEpayments — there is no client-facing endpoint for them. Their outcome reaches you through the onboarding **webhook**. ## Status Flow ```mermaid theme={null} graph LR A[pending] --> B[pending_documents] B --> C[documents_under_review] C -->|rejection| B C -->|close| E[canceled] C -->|national| S[waiting_signature] C -->|cross-border| K[waiting_bank_channel] S -->|signed| D[active] K --> P[bank_channel_in_progress] P --> L[bank_channel_created] L --> D[active] D --> F[inactive] D --> G[closed] style A fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#000 style B fill:#ede9fe,stroke:#8b5cf6,stroke-width:2px,color:#000 style C fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#000 style S fill:#ffedd5,stroke:#f97316,stroke-width:2px,color:#000 style K fill:#cffafe,stroke:#06b6d4,stroke-width:2px,color:#000 style P fill:#cffafe,stroke:#06b6d4,stroke-width:2px,color:#000 style L fill:#ccfbf1,stroke:#14b8a6,stroke-width:2px,color:#000 style D fill:#d1fae5,stroke:#10b981,stroke-width:2px,color:#000 style E fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#000 style F fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#000 style G fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#000 ``` | Status | Meaning | | - | - | | `pending` | Solicitation received and awaiting processing. | | `pending_documents` | The required documents were resolved from the company's segment + modality and attached to the solicitation. The webhook for this status carries the `documents` list. The solicitation stays here until **all required** documents are sent. | | `documents_under_review` | Every required document was sent. Compliance is reviewing them. | | `waiting_signature` | *National only.* Documents approved; the contract is awaiting signature by the legal representatives. | | `waiting_bank_channel` | *Cross-border only.* Documents approved; the bank channel opening was requested and is waiting to start. | | `bank_channel_in_progress` | *Cross-border only.* WEpayments is opening the bank channel. | | `bank_channel_created` | *Cross-border only.* The bank channel was created; the account is being finalized. | | `active` | The account was created. The webhook delivers the `account_id` (MID — Merchant ID). | | `canceled` | Onboarding did not proceed — compliance closed the solicitation. The webhook carries a `reason` object with the closure `code` and `detail`. | | `inactive` / `closed` | Terminal states of an account that was previously `active`. | > [!NOTE] > > A `reject` decision sends the solicitation **back to `pending_documents`**, keeping the already‑approved documents untouched, so the client only needs to resend the rejected ones. > [!NOTE] > > A **closure** is final: the solicitation moves to `canceled`, every requested document is rejected and the analysis stops. There is no reopening — a new evaluation requires a new solicitation. ## Modality: national vs cross-border The modality is **derived from the company address country**, not sent as an input: * `address.country` = `BR` → **national** (contract signature step). * `address.country` ≠ `BR` → **cross-border** (bank channel step, no signature). The modality also affects which documents are required (segment + modality), so the `documents` list you receive already matches the company's modality. ## Document fields Each requested document carries two independent state machines: | Field | Owner | Values | | - | - | - | | `upload_status` | **Client** (via upload) | `pending` → `sent` | | `review_status` | **Compliance** (via review) | `pending` → `approved` / `rejected` | A document is only uploadable when `upload_status` is `pending` **or** `review_status` is `rejected`. Approved documents cannot be replaced. ## Step-by-step **1. Register the onboarding webhook** Subscribe to onboarding updates with [Webhook Setup](/api-reference/account/webhook/webhook-setup) **before opening the solicitation** — this way you won't miss the `pending_documents` event, which is fired right after the solicitation is processed and carries the list of required documents. Every status change is delivered to your URL, which must answer `200 OK`; otherwise delivery is retried **up to 3 times, every 15 minutes**. > [!WARNING] > > Register the webhook first. If you create the solicitation before subscribing, you may miss the `pending_documents` notification. You can still recover the list with [List Documents](/api-reference/account/documents/list-documents), but reacting to the webhook is the intended flow. **2. Create the solicitation with a segment** Open the corporate account through [`POST /v2/register/companies`](/api-reference/account/create), including the `segment` object. Use [List Segments](/api-reference/account/segments/list-segments) to obtain a valid `segment.id`. The solicitation is created with status `pending`. ```json Request (excerpt) theme={null} { "legal_name": "Company X LTDA", "trade_name": "Company X", "tax_id": "12345678000199", "website": "https://www.companyx.com", "segment": { "id": 7 }, "address": { "country": "BR", "...": "..." } } ``` > [!WARNING] > > Without a `segment`, the document flow does **not** run — the solicitation stays on the flow configured for the merchant. The segment must reference an existing segment, otherwise the request fails with `422`. The `address.country` defines the modality (national vs cross-border). **3. Receive the required documents (pending\_documents)** Once the solicitation is processed, its status becomes `pending_documents` and the webhook payload includes the `documents` array — the exact list the client must send. ```json Webhook theme={null} { "id": "1234-5678-90ab-cdef-1234567890ab", "status": "pending_documents", "updated_at": "2024-01-15T10:30:00.000000Z", "account_id": null, "documents": [ { "name": "Articles of Incorporation", "tag": "articles_of_incorporation", "description": "Company's current articles of incorporation", "required": true, "upload_status": "pending", "review_status": "pending" } ] } ``` Store each `tag` — it is the identifier you use to upload the matching file. **4. Upload the documents (partial or complete)** Send each file with [`POST /v2/register/companies/{uuid}/documents`](/api-reference/account/documents/upload-document) as `multipart/form-data` (`tag` + `file`). You may upload in several calls. Each successful upload sets that document's `upload_status` to `sent` and triggers the onboarding webhook with the updated state. Accepted files: **pdf, jpg, jpeg, png**, up to **15 MB** each (also returned per document as `max_size_kb`). **5. Automatic transition to review** After every upload, WEpayments checks whether **all required** documents are `sent`. When they are, the solicitation moves automatically to `documents_under_review` — **optional documents do not block** this transition. The webhook fired by that last upload already reflects the new status. **6. Compliance reviews the documents** Compliance approves or rejects each document. You are notified through the webhook: * **All approved →** the flow branches by modality: **national** moves to `waiting_signature`; **cross-border** moves to `waiting_bank_channel`. * **Any rejection →** the solicitation goes back to `pending_documents`; the rejected document returns to `upload_status: pending` / `review_status: rejected` (with a `reason`), while approved documents are preserved. * **Review closed →** the solicitation becomes `canceled`, and the webhook carries a `reason` object with the closure `code` and `detail`. **7. Sign the contract — national only (waiting\_signature)** When the status is `waiting_signature`, fetch the signing links with [`GET /v2/register/companies/{uuid}/signature/link`](/api-reference/account/signature/signature-link) and route **each signer** to their `sign_url` (ZapSign). Once every signer has signed, WEpayments creates the account and the solicitation moves to `active`. You can download the signed contract at any time with `GET /v2/register/companies/{uuid}/signature/file`. > [!NOTE] > > Cross-border solicitations skip this step — there is no signature. Calling the signature endpoints for a cross-border solicitation returns `404`. **8. Bank channel opening — cross-border only (waiting\_bank\_channel)** When the status is `waiting_bank_channel`, WEpayments opens the bank channel internally. There is nothing to do on the merchant side — just watch the webhook: the solicitation moves to `bank_channel_in_progress` while the channel is being opened, then to `bank_channel_created` and finally to `active`. **9. Account activation (active)** When the status becomes `active`, the webhook delivers the `account_id` (MID — Merchant ID). The account is ready to transact. ## Tracking the documents At any time you can call [`GET /v2/register/companies/{uuid}/documents`](/api-reference/account/documents/list-documents) to read the current state of every document and its immutable `review_history` (approvals and rejections, newest first). This is a **read-only** call — it never changes the solicitation status. ```json Response (excerpt) theme={null} { "id": "1234-5678-90ab-cdef-1234567890ab", "status": "documents_under_review", "documents": [ { "tag": "articles_of_incorporation", "upload_status": "sent", "review_status": "approved", "review_history": [ { "action": "approved", "timestamp": "2024-01-18T10:00:00.000000Z" }, { "action": "rejected", "timestamp": "2024-01-16T10:00:00.000000Z", "reason": "Illegible document" } ] } ] } ``` ## Best practices > [accordion] Always drive the upload from the webhook's tags > > Don't hardcode the document list — it depends on the company's segment and modality. Read the `documents` array from the `pending_documents` webhook (or from the documents query) and upload each file by its `tag`. An unknown tag is rejected with `422`. > [accordion] Handle partial uploads > > Required documents can be sent across multiple calls. The solicitation only advances to `documents_under_review` when **all required** documents are `sent`. Optional documents never block the transition. > [accordion] React to rejections automatically > > On a rejection, the solicitation returns to `pending_documents` and the webhook carries the rejected document with its `reason`. Surface that `reason` to the client and allow a resend of the same `tag`. > [accordion] Branch your handling by status, not by assumption > > After approval the next status depends on modality: `waiting_signature` (national) or `waiting_bank_channel` (cross-border). Only the national branch requires action from you (routing signers to their `sign_url`); the cross-border branch is fully handled by WEpayments. > [accordion] Make your webhook idempotent > > A webhook is fired on every upload and every status change, so you may receive several events for the same solicitation. Use `id` + `status` (and the per-document state) to reconcile, and always answer `200 OK`. The `documents` array is only present in `pending_documents`, `documents_under_review` and `canceled`; the `reason` object only in `canceled`. ## Related resources > [card] [Create Company](/api-reference/account/create) > > Open the solicitation with a segment > [card] [Onboarding Webhook](/api-reference/account/webhook/onboarding-documents) > > Payload and statuses delivered to your URL > [card] [Upload Document](/api-reference/account/documents/upload-document) > > Send the required files by tag > [card] [List Documents](/api-reference/account/documents/list-documents) > > Query state and review history > [card] [Get Signature Link](/api-reference/account/signature/signature-link) > > Route representatives to sign the contract (national) # Reference Source: https://docs.wepayout.co/account/reference Understanding account management in WEpayments # Account Reference The WEpayments account system allows you to onboard new businesses and manage their verification process through our API. ## What is an Account? An account represents a business entity that wants to use WEpayments services. Each account goes through a verification process before being approved for transactions. ## Account Lifecycle **1. Account Opening** Submit business information and documentation through the API **2. Verification** Our compliance team reviews the submitted information **3. Approval/Rejection** Account is either approved or rejected with feedback **4. Active** Approved accounts can start processing transactions ## Key Features > [card] Automated Onboarding > > Programmatically create and manage accounts via API > [card] Real-time Notifications > > Receive webhook notifications for status changes > [card] Document Management > > Submit and track required documentation > [card] Compliance Ready > > Built-in KYC/KYB verification process ## Account Status > [!NOTE] > > A new onboarding flow is available (opt-in **per merchant** via feature flag): when enabled for a merchant, a company created with a segment moves to `pending_documents` and the webhook delivers the required documents. See [Onboarding Documents Flow](/api-reference/account/webhook/onboarding-documents). The flow described below remains the current default. ### Status Flow ```mermaid theme={null} graph LR A[pending] --> B[due_diligence_review] B --> C[active] B --> D[canceled] C --> E[inactive] C --> F[closed] style A fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#000 style B fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#000 style C fill:#d1fae5,stroke:#10b981,stroke-width:2px,color:#000 style D fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#000 style E fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#000 style F fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#000 ``` ### Status Types > [accordion] pending > > **Description**: First status of the process. Indicates that the account opening request has been received and is awaiting review. > > **Next Steps**: Wait for compliance team to start the review process > > **Typical Duration**: 1-2 business days > [accordion] due\_diligence\_review > > **Description**: Compliance is analyzing the Due Diligence (DD) and company data provided during onboarding. > > **Next Steps**: May request additional documentation if needed > > **Typical Duration**: 2-5 business days > [accordion] active > > **Description**: Account is active/approved. At this status, the webhook will send the `account_id` (MID - Merchant ID) that identifies the merchant's account. > > **Next Steps**: Start processing transactions > > **Actions Available**: All API endpoints accessible > [accordion] canceled > > **Description**: Account was canceled during the onboarding process. > > **Next Steps**: Review the closure reason and submit a new request if the cause can be addressed. A canceled solicitation cannot be reopened. > > **Reasons**: Delivered in the webhook as a `reason` object with a `code` from a closed catalogue — `restriction_list`, `segment_not_allowed`, `duplicate_request`, `no_customer_response`, `customer_withdrawal` or `other` — and a standardised `detail`. See [Onboarding Documents Flow](/api-reference/account/webhook/onboarding-documents#webhook-payload). > [accordion] inactive > > **Description**: Account is inactive after being previously activated. > > **Next Steps**: Contact support to understand the reason and reactivation process > [accordion] closed > > **Description**: Account has been closed. > > **Next Steps**: Account cannot be reactivated. A new account opening request is required if needed. ## Required Information To open an account, you need to provide: ### Business Information * Legal business name * Business document (CNPJ for Brazil) * Business email and phone * Complete business address ### Representative Information * Full name of legal representative * Personal document (CPF for Brazil) * Email and phone * Birth date ### Additional Documents Depending on your business type, you may need to provide: * Articles of incorporation * Proof of address * Bank account information * Business licenses ## API Endpoints The Account API provides the following endpoints: | Endpoint | Method | Description | | - | - | - | | `/v2/register/companies` | POST | Create new account opening request | | `/v2/register/companies/webhooks` | POST | Register webhook for notifications | | `/v2/register/companies/webhooks` | GET | List registered webhooks | | `/v2/register/companies/webhooks` | PUT | Update webhook configuration | | `/v2/register/companies/webhooks` | DELETE | Remove webhook | ## Next Steps > [card] [Opening Process](/account/opening-process) > > Learn how to create an account > [card] [Webhook Integration](/account/webhook-integration) > > Set up real-time notifications > [card] [API Reference](/api-reference/account/create) > > View complete API documentation > [card] [Authentication](/authentication) > > Learn about API authentication ## Need Help? **24/7 Support Team**: Our Support, Performance & CX team is available for operational and technical assistance. * 📚 **Help Center**: Access articles on panel usage, transactions, payments, withdrawals, reports, and more. [Visit Help Center](https://support.wepayments.com.br/) * 💬 **Chat**: Click the chat icon in the bottom-right corner of any Help Center page * 📱 **WhatsApp**: [+55 41 9266-7191](https://wa.me/5541926677191) * 📧 **E-mail**: [cs@wepayments.com.br](mailto:cs@wepayments.com.br) # Change Fee Target Account Source: https://docs.wepayout.co/api-reference/account/change-fee-target POST /v2/account/{merchantId}/fee-target Transfer Cashout fee from one account to another within the same customer domain This endpoint allows the transfer of a Cashout fee (Payout/Cashout fee) to another account within the same customer domain. This functionality is useful when fee charges need to be reallocated between internal accounts belonging to the same customer (e.g., between segregated wallets or cost centers). ## Business Rules > [!WARNING] > > **Important Restrictions**: > > * The target account must belong to the same customer domain as the original account > * After the transfer, the fee becomes exclusively associated with the new account, but it remains linked to the originating entity of the fee > * Fees related to Payin/Cashin transactions are not affected by this functionality — they will continue to be charged to the originating account (i.e., the account where the Cashin occurred) > [!NOTE] > > **Note**: This setting only defines which wallet will be charged the merchant fee, but it does not change the operational model (prepaid or postpaid) of the merchant itself. ### Prepaid Model The destination wallet must have sufficient balance at the time of the fee charge. ### Postpaid Model The destination wallet does not need to have sufficient balance, but all fees will be consolidated and invoiced monthly by the WEpayments finance team. ## About Removing This Setting > [!NOTE] > > **Update as of 2023-06-11**: Currently, this removal cannot be performed via API. If you need to remove this configuration, please contact our CA team to request the change. In the coming weeks, new account management endpoints will be made available to support this functionality, eliminating the need to open a support ticket with our CA team. ## Path Parameters **merchantId** `string` *required* Merchant ID ## Request Body **merchant\_fee** `integer` *required* Provide the ID of the account that should receive the fees from the account you are updating (the account specified in the endpoint path). **Important**: Your "Free fee" to be charged to the destination account should be posted to the fee wallet. **fee\_wallet** `boolean` Indicate "true" if the fee to be charged to the destination account should be posted to the fee wallet. ## Response **id** `integer` Account ID **merchant\_id** `integer` Merchant ID **recipient\_id** `integer or null` Recipient ID **currency\_id** `integer` Currency ID **account\_fee** `object or null` Account fee configuration **id** `integer` Fee configuration ID **merchant\_id** `integer` Merchant ID **currency\_id** `integer` Currency ID **use\_fee\_billing** `boolean` Whether fee billing is enabled ## Request Example ```bash cURL theme={null} curl --request POST \ --url https://api.sandbox.wepayout.com.br/v2/account/{merchantId}/fee-target \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' \ --header 'Content-Type: application/json' \ --data '{ "merchant_fee": 1234, "fee_wallet": true }' ``` ```javascript JavaScript theme={null} const merchantId = 'your_merchant_id'; const response = await fetch( `https://api.wepayments.com/v2/account/${merchantId}/fee-target`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ merchant_fee: 123, fee_wallet: true }) } ); const data = await response.json(); console.log('Fee target updated:', data); ``` ```python Python theme={null} import requests merchant_id = 'your_merchant_id' url = f'https://api.wepayments.com/v2/account/{merchant_id}/fee-target' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' } data = { 'merchant_fee': 123, 'fee_wallet': True } response = requests.post(url, headers=headers, json=data) result = response.json() print(f"Fee target updated: {result}") ``` ```json 200 OK theme={null} { "id": 0, "merchant_id": 0, "recipient_id": 0, "currency_id": 0, "account_fee": { "id": 0, "merchant_id": 0, "currency_id": 0, "use_fee_billing": true } } ``` ```json 401 Unauthorized theme={null} { "error": "Unauthorized" } ``` ```json 500 Internal Server Error theme={null} { "error": "Internal server error" } ``` ## Use Cases > [accordion] Centralize Fee Management > > Route all fees to a dedicated fee management account: > > ```javascript theme={null} > async function centralizeFees(merchantId, feeAccountId) { > const response = await fetch( > `https://api.wepayments.com/v2/account/${merchantId}/fee-target`, > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_TOKEN', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > merchant_fee: feeAccountId, > fee_wallet: true > }) > } > ); > > return await response.json(); > } > > // Route all fees from account 456 to central fee account 789 > await centralizeFees(456, 789); > ``` > [accordion] Cost Center Allocation > > Allocate fees to specific cost centers: > > ```javascript theme={null} > async function allocateFeesToCostCenter(accounts, costCenterId) { > const results = []; > > for (const accountId of accounts) { > const result = await fetch( > `https://api.wepayments.com/v2/account/${accountId}/fee-target`, > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_TOKEN', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > merchant_fee: costCenterId, > fee_wallet: true > }) > } > ); > > results.push({ > accountId, > status: result.status, > data: await result.json() > }); > } > > return results; > } > > // Allocate fees from multiple accounts to cost center > const accounts = [101, 102, 103]; > await allocateFeesToCostCenter(accounts, 999); > ``` > [accordion] Segregated Wallet Management > > Manage fees across segregated wallets: > > ```javascript theme={null} > async function setupSegregatedWalletFees(mainWalletId, feeWalletId) { > // Configure main wallet to send fees to fee wallet > const response = await fetch( > `https://api.wepayments.com/v2/account/${mainWalletId}/fee-target`, > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_TOKEN', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > merchant_fee: feeWalletId, > fee_wallet: true > }) > } > ); > > const result = await response.json(); > > return { > mainWallet: mainWalletId, > feeWallet: feeWalletId, > configuration: result > }; > } > ``` > [accordion] Multi-Account Fee Routing > > Set up fee routing for multiple accounts: > > ```javascript theme={null} > async function setupMultiAccountFeeRouting(feeRoutingConfig) { > const results = []; > > for (const config of feeRoutingConfig) { > try { > const response = await fetch( > `https://api.wepayments.com/v2/account/${config.sourceAccount}/fee-target`, > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_TOKEN', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > merchant_fee: config.targetAccount, > fee_wallet: config.useFeeWallet > }) > } > ); > > results.push({ > source: config.sourceAccount, > target: config.targetAccount, > success: response.ok, > data: await response.json() > }); > } catch (error) { > results.push({ > source: config.sourceAccount, > target: config.targetAccount, > success: false, > error: error.message > }); > } > } > > return results; > } > > // Usage > const config = [ > { sourceAccount: 101, targetAccount: 201, useFeeWallet: true }, > { sourceAccount: 102, targetAccount: 201, useFeeWallet: true }, > { sourceAccount: 103, targetAccount: 202, useFeeWallet: false } > ]; > > const results = await setupMultiAccountFeeRouting(config); > console.log('Fee routing setup:', results); > ``` ## Important Considerations ### Fee Types Affected > [card] Affected > > **Cashout/Payout Fees** > > * Withdrawal fees > * Transfer fees > * Payout processing fees > [card] Not Affected > > **Cashin/Payin Fees** > > * Deposit fees > * Payment processing fees > * Remain on original account ### Payment Models > [tab] Prepaid > > **Prepaid Model Requirements**: > > * Destination account must have sufficient balance > * Fees are deducted immediately > * Transaction fails if insufficient funds > > ```javascript theme={null} > // Check balance before setting fee target > const balance = await getBalance(targetAccountId); > if (balance.available_balance >= expectedFees) { > await changeFeeTarget(sourceAccountId, targetAccountId); > } > ``` > [tab] Postpaid > > **Postpaid Model Characteristics**: > > * No balance requirement > * Fees are consolidated monthly > * Invoiced by WEpayments finance team > * Better for high-volume operations > > ```javascript theme={null} > // Postpaid setup - no balance check needed > await changeFeeTarget(sourceAccountId, targetAccountId, { > fee_wallet: true > }); > ``` ## Best Practices > [!NOTE] > > **Same Customer Domain**: Ensure both source and target accounts belong to the same customer domain before attempting the transfer. > [!WARNING] > > **Fee Wallet Configuration**: When using `fee_wallet: true`, ensure the destination account is properly configured as a fee wallet. > [!TIP] > > **Audit Trail**: Keep a log of all fee target changes for accounting and reconciliation purposes. # Account Opening Request Source: https://docs.wepayout.co/api-reference/account/create POST https://api.sandbox.wepayout.com.br/v2/register/companies API for creating onboarding requests for corporate account (legal entities). To successfully create a corporate account, you must provide at least one administrator and one legal representative. ## Allowed Roles | Role | Required | | - | - | | administrator | ✓ | | legal\_representative | ✓ | | financial | ✗ | | commercial | ✗ | | compliance | ✗ | ## Request Body **legal\_name** `string` *required* Official registered name of the company as it appears in legal documents. * Min: 1 character * Max: 150 characters * Example: `Company X LTDA` **trade\_name** `string` *required* Common or commercial name used by the company in business operations. * Min: 1 character * Max: 150 characters * Example: `Company X` **tax\_id** `string` *required* Company's tax identification number (CNPJ for Brazilian companies), without formatting. * If country = BR: exactly 14 characters (valid CNPJ), in either format issued by the Receita Federal: * **numeric** — 14 digits, e.g. `12345678000199`; * **alphanumeric** (issued since July 2026) — letters and digits in the first 12 positions, the 2 check digits always numeric, e.g. `12ABC34501DE35`. * If country ≠ BR: max 50 characters * Letters are normalized to upper case, and the mask separators (`.`, `/` and `-`) are removed before validation — so `12.abc.345/01de-35` is stored as `12ABC34501DE35`. The expected format is still the unformatted one. * Must be **unique per parent** — a parent cannot have two solicitations with the same `tax_id`, compared on the normalized value. * Example: `12345678000199` **website** `string` *required* Company's website. * Max: 255 characters * Accepted as free text: the API checks only the length, not the URL format. * Example: `https://www.companyx.com` **parent\_id** `integer` Identifier of the **merchant** (level 1 in the account hierarchy) the solicitation will be created under. When omitted, your own company is used as the parent — which must itself be a merchant. A master/holding account (level 0) has no implicit merchant and **must** provide a `parent_id`. The `parent_id` must belong to your accessible companies and be a merchant; otherwise the request fails with `422`. * Example: `1024` **contacts** `array[object]` *required* List of individuals associated with the company, such as administrators, legal representatives, or other relevant roles. **Contact Object** **name** `string` *required* Full name of the contact person. * Min: 1 character * Max: 120 characters * Example: `João Silva` **email** `string` *required* Contact's professional email address. * Max: 100 characters * Example: `joao.silva@companyx.com` **phone** `string` *required* Contact's phone number, including country and area code. * Max: 15 characters * Example: `5511999999999` **role** `string` *required* Role of the contact person within the company. Must be one of the allowed roles. * Allowed values: `administrator`, `legal_representative`, `financial`, `commercial`, `compliance` * Example: `administrator` **tax\_id** `string` *required* Personal tax identification number of the contact (CPF for Brazil), without formatting. * If country = BR: max 11 characters (valid CPF) * If country ≠ BR: max 30 characters * Example: `12345678909` **address** `object` *required* Company's main business address. **Address Object** **city** `string` *required* City where the company is located. * Max: 40 characters * Example: `São Paulo` **state** `string` *required* State or province where the company is located (ISO code preferred). * Max: 4 characters * Example: `SP` **country** `string` *required* Country code where the company is registered (ISO 3166-1 alpha-2 format). * Max: 4 characters * Example: `BR` **zip\_code** `string` *required* Postal code of the company address, without formatting. * Max: 12 characters * Example: `01001000` **street** `string` *required* Street name of the company address. * Max: 80 characters * Example: `Av. Paulista` **number** `string` Street number of the company address. * Max: 10 characters * Example: `1000` **complement** `string` Additional address details, such as suite, floor, or unit. * Max: 80 characters * Example: `Conjunto 12` **segment** `object` Optional business segment to associate with the company at creation time. When omitted, the company is created without a segment. **Segment Object** **id** `integer` Unique identifier of the segment. Must reference an existing segment, otherwise the request fails with `422 Unprocessable Entity`. * Example: `7` > [!TIP] > > To obtain a valid `segment.id`, call the [List Segments](/api-reference/account/segments/list-segments) endpoint (`GET /v2/register/segments`) and use the `id` of the desired segment. You can also fetch a single segment with `GET /v2/register/segments?id={id}` to confirm it exists before sending it. ## Response > [!NOTE] > > On a `422`, `fields` maps each rejected field to its messages. The key is the path of the field in > the payload you sent — `tax_id`, `address.city`, `contacts.0.email` — so you can show the message > next to the input that caused it. Messages follow the language of the authenticated user. **id** `string` Unique identifier of the corporate subaccount opening request. * Format: UUID * Example: `339074a8-1834-49c5-af94-4a044248d88d` **status** `string` Current status of the onboarding request. * Default: `pending` ```json 201 Created theme={null} { "id": "339074a8-1834-49c5-af94-4a044248d88d", "status": "pending" } ``` ```json 422 Unprocessable Entity theme={null} { "error_code": "validation", "error_description": "Validation error", "fields": { "legal_name": ["The legal name field is required."], "tax_id": ["The tax id must be a valid CNPJ."], "contacts.0.email": ["The contact e-mail field must be a valid email address."] } } ``` ## Related Resources > [card] [Setup Webhook](/api-reference/account/webhook/webhook-setup) > > Configure webhook notifications for onboarding events > [card] [Update Webhook](/api-reference/account/webhook/webhook-update) > > Update existing webhook configuration > [card] [List Segments](/api-reference/account/segments/list-segments) > > Retrieve segment IDs to associate with a company # List Documents Source: https://docs.wepayout.co/api-reference/account/documents/list-documents GET /v2/register/companies/{uuid}/documents Read the documents linked to an onboarding solicitation, including each document's upload/review state and its immutable decision history. Read-only — does not change the solicitation status. > [!NOTE] > > Part of the [Onboarding Documents flow](/account/onboarding-documents-flow). This endpoint reflects the current state and history of each document — uploads, resends and compliance decisions. It returns **only** the documents linked to the given solicitation and never alters its status. ## Path Parameters **uuid** `string` *required* UUID of the solicitation (the `id` returned by [Create Company](/api-reference/account/create)). * Format: UUID * Example: `339074a8-1834-49c5-af94-4a044248d88d` ## Response **id** `string` UUID of the solicitation. **status** `string` Current status of the solicitation (e.g. `pending_documents`, `documents_under_review`). **documents** `array` Documents linked to the solicitation. **document object** **name** `string` Human-readable name of the document. **tag** `string` Machine-readable identifier of the document type — the value used to upload it. **description** `string` Description of what the document is. **required** `boolean` Whether the document is mandatory for the onboarding to proceed. **upload\_status** `string` Upload state, owned by the client. One of `pending`, `sent`. **review\_status** `string` Compliance review state. One of `pending`, `approved`, `rejected`. **max\_size\_kb** `integer` Maximum file size accepted for this document, in KB. Currently `15360` (15 MB) for every document. **created\_at** `string | null` When the document was attached to the solicitation. ISO 8601. **updated\_at** `string | null` Last time the document state changed. ISO 8601. **sent\_at** `string | null` When the document was last sent. `null` if never uploaded. **reviewed\_at** `string | null` When the last review decision was taken. Always reflects the **latest** decision. `null` if not reviewed yet. **review\_history** `array` Immutable list of review decisions, ordered by date **descending** (newest first). Empty until the first decision. **event object** **action** `string` The decision. One of `approved`, `rejected`. **timestamp** `string` When the decision was taken. ISO 8601. **reason** `string` Reason for the decision. Present only on `rejected` events. ```json 200 OK theme={null} { "id": "1234-5678-90ab-cdef-1234567890ab", "status": "documents_under_review", "documents": [ { "name": "Articles of Incorporation", "tag": "articles_of_incorporation", "description": "Company's current articles of incorporation", "required": true, "upload_status": "sent", "review_status": "approved", "max_size_kb": 15360, "created_at": "2024-01-10T10:00:00.000000Z", "updated_at": "2024-01-18T10:00:00.000000Z", "sent_at": "2024-01-17T10:00:00.000000Z", "reviewed_at": "2024-01-18T10:00:00.000000Z", "review_history": [ { "action": "approved", "timestamp": "2024-01-18T10:00:00.000000Z" }, { "action": "rejected", "timestamp": "2024-01-16T10:00:00.000000Z", "reason": "Illegible document" } ] }, { "name": "Proof of Address", "tag": "proof_of_address", "description": "Updated proof of address", "required": true, "upload_status": "sent", "review_status": "rejected", "max_size_kb": 15360, "created_at": "2024-01-10T10:00:00.000000Z", "updated_at": "2024-01-16T10:00:00.000000Z", "sent_at": "2024-01-15T11:00:00.000000Z", "reviewed_at": "2024-01-16T10:00:00.000000Z", "review_history": [ { "action": "rejected", "timestamp": "2024-01-16T10:00:00.000000Z", "reason": "Address mismatch" } ] }, { "name": "Balance Sheet", "tag": "balance_sheet", "description": "Financial balance sheet", "required": false, "upload_status": "pending", "review_status": "pending", "max_size_kb": 15360, "created_at": "2024-01-10T10:00:00.000000Z", "updated_at": "2024-01-10T10:00:00.000000Z", "sent_at": null, "reviewed_at": null, "review_history": [] } ] } ``` ```json 403 Access denied theme={null} { "message": "Access denied to this solicitation" } ``` ```json 404 Not found theme={null} { "message": "Solicitation not found" } ``` ## Errors | Status | When | | - | - | | `404` | Solicitation does not exist. | | `403` | Solicitation exists but is not accessible with the authenticated credentials. | ## Download a document file To retrieve the **latest uploaded file** of a specific document, call: ``` GET /v2/register/companies/{uuid}/documents/{tag}/file ``` **tag** `string` *required* The `tag` of the document whose file you want to download (e.g. `articles_of_incorporation`). The response streams the file as a binary download (with its original file name). If the solicitation has no file for that tag yet, it returns `404`. | Status | When | | - | - | | `200` | File returned as a download. | | `404` | Solicitation not found, or no file uploaded for that tag. | | `403` | Solicitation not accessible with the authenticated credentials. | ```bash cURL theme={null} curl -X GET "https://api.sandbox.wepayout.com.br/v2/register/companies/339074a8-1834-49c5-af94-4a044248d88d/documents/articles_of_incorporation/file" \ -H "Authorization: Bearer YOUR_API_KEY" \ -o articles_of_incorporation.pdf ``` ## Related Resources > [card] [Onboarding Documents Integration](/account/onboarding-documents-flow) > > Understand the full flow > [card] [Upload Document](/api-reference/account/documents/upload-document) > > Send the required files by tag # Upload Document Source: https://docs.wepayout.co/api-reference/account/documents/upload-document POST /v2/register/companies/{uuid}/documents Upload a single document of an onboarding solicitation, identified by its tag. Supports partial uploads — once all required documents are sent, the solicitation moves automatically to documents_under_review. > [!NOTE] > > Part of the [Onboarding Documents flow](/account/onboarding-documents-flow). The request is `multipart/form-data` with two fields: `tag` and `file`. Send **one document per call**; you may call it multiple times to upload the documents partially. ## Path Parameters **uuid** `string` *required* UUID of the solicitation (the `id` returned by [Create Company](/api-reference/account/create)). Must be in a status that accepts uploads (`pending_documents` or `documents_under_review`). * Format: UUID * Example: `339074a8-1834-49c5-af94-4a044248d88d` ## Request Body > [!NOTE] > > Content-Type: `multipart/form-data`. **tag** `string` *required* Identifier of the document being sent. Must match one of the `tag` values listed for the solicitation (delivered in the `pending_documents` webhook or returned by [List Documents](/api-reference/account/documents/list-documents)). An unrecognized tag is rejected with `422`. * Example: `articles_of_incorporation` **file** `file` *required* The document file. * Accepted formats: `pdf`, `jpg`, `jpeg`, `png` * Maximum size: **15 MB** (also returned per document as `max_size_kb` by [List Documents](/api-reference/account/documents/list-documents)) ## Behavior * A successful upload sets the document's `upload_status` to `sent`. * After each upload, if **all required** documents are `sent`, the solicitation moves **automatically** to `documents_under_review`. Optional documents do not block this transition. * The [onboarding webhook](/api-reference/account/webhook/onboarding-documents) is fired on every upload, reflecting the updated state. * **Resending a rejected document:** uploading a document whose `review_status` is `rejected` sets `upload_status` back to `sent` and `review_status` back to `pending`. The previous rejection `reason` is preserved in the document history and is not returned in the active document state. > [!WARNING] > > Upload is only allowed when the document's `upload_status` is `pending` **or** its `review_status` is `rejected`. A document already `approved` cannot be replaced, and a document already `sent` and awaiting review cannot be re-sent — both return `422`. ## Response **message** `string` Confirmation message. ```json 200 OK theme={null} { "message": "Document uploaded successfully" } ``` ```json 422 Invalid tag theme={null} { "message": "The provided tag is not part of the solicitation documents" } ``` ```json 422 Already approved theme={null} { "message": "Document already approved and cannot be replaced" } ``` ```json 422 Already submitted theme={null} { "message": "Document already submitted and is awaiting review" } ``` ```json 413 File too large theme={null} { "error_code": "validation", "error_description": "Validation error", "fields": { "file": ["The file must not be larger than 15 MB."] }, "field_errors": [ { "field": "file", "code": "file_too_large", "params": { "max_size_kb": 15360, "max_size_mb": 15 }, "message": "The file must not be larger than 15 MB." } ] } ``` ```json 422 Invalid format theme={null} { "error_code": "validation", "error_description": "Validation error", "fields": { "file": ["The file field must be a file of type: pdf, jpg, jpeg, png."] }, "field_errors": [ { "field": "file", "code": "invalid_file", "params": { "values": ["pdf", "jpg", "jpeg", "png"] }, "message": "The file field must be a file of type: pdf, jpg, jpeg, png." } ] } ``` ```json 409 Invalid status theme={null} { "message": "Solicitation does not accept document uploads in its current status" } ``` ```json 404 Not found theme={null} { "message": "Solicitation not found" } ``` ## Errors Errors that belong to a field of the request (`file`) follow the same `field_errors` contract as the other validation errors: use `code` to build your own message and `params` for its values, or render the translated `message`. The other errors return a single `message`. Messages are translated to the user's language. | Status | When | | - | - | | `422` | Tag not part of the solicitation, document already approved or already submitted (`message`), or file missing or not in `pdf, jpg, jpeg, png` (`field_errors` with code `required` or `invalid_file`). | | `413` | File larger than 15 MB (`field_errors` with code `file_too_large`). | | `409` | Solicitation is not in `pending_documents` nor `documents_under_review`. | | `404` | Solicitation not found or not accessible. | ## Examples ```bash cURL theme={null} curl -X POST "https://api.sandbox.wepayout.com.br/v2/register/companies/339074a8-1834-49c5-af94-4a044248d88d/documents" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "tag=articles_of_incorporation" \ -F "file=@/path/to/articles_of_incorporation.pdf" ``` ```javascript JavaScript theme={null} const form = new FormData(); form.append("tag", "articles_of_incorporation"); form.append("file", fileInput.files[0]); // a pdf/jpg/jpeg/png up to 15 MB const response = await fetch( "https://api.sandbox.wepayout.com.br/v2/register/companies/339074a8-1834-49c5-af94-4a044248d88d/documents", { method: "POST", headers: { Authorization: "Bearer YOUR_API_KEY" }, body: form, } ); const data = await response.json(); console.log(data.message); ``` ```python Python theme={null} import requests url = "https://api.sandbox.wepayout.com.br/v2/register/companies/339074a8-1834-49c5-af94-4a044248d88d/documents" headers = {"Authorization": "Bearer YOUR_API_KEY"} data = {"tag": "articles_of_incorporation"} with open("articles_of_incorporation.pdf", "rb") as f: files = {"file": ("articles_of_incorporation.pdf", f, "application/pdf")} response = requests.post(url, headers=headers, data=data, files=files) print(response.json()["message"]) ``` ## Related Resources > [card] [Onboarding Documents Integration](/account/onboarding-documents-flow) > > Understand the full flow > [card] [List Documents](/api-reference/account/documents/list-documents) > > Query state and review history # Get Account Opening Request By ID Source: https://docs.wepayout.co/api-reference/account/get-account-by-id GET /v2/register/companies/{id} Retrieve a single account opening request using its unique identifier. Returns all details of the request including company information, contacts, addresses, status, and history. ## Path Parameters **id** `string` *required* Unique identifier of the account opening request ## Response Body **id** `string` Unique identifier of the account opening request **company** `object` Company information **Company Details** **legal\_name** `string` Company’s registered legal name **trade\_name** `string` Company’s trade name or business name **tax\_id** `string` Company’s tax identification number (CNPJ), without separators. The first 12 characters may be digits or uppercase letters; the last 2 are always numeric check digits. **website** `string` Company’s website, as sent on the solicitation. `null` for solicitations created before this field existed **contacts** `array` List of contact persons associated with the company. Each object represents a contact. **Contact** **name** `string` Full name of the contact person **email** `string` Email address of the contact person **phone** `string` Phone number including country and area code **tax\_id** `string` Contact’s individual tax ID (CPF), numbers only **role** `string` Role within the company Allowed values: `administrator`, `legal_representative`, `financial`, `commercial`, `compliance` **address** `array` List of addresses related to the company **Address** **city** `string` City name **state** `string` State abbreviation (UF) **country** `string` ISO 3166-1 alpha-2 country code **zip\_code** `string` Postal code (CEP), numbers only **street** `string` Street or public place name **number** `string` Address number **complement** `string` Address complement, if any **status** `string` Current status of the account opening request Values: `pending`, `due_diligence_review`, `active`, `inactive`, `canceled`, `closed` **status\_history** `array` List of all previous status changes for the request **Status History** **status** `string` Status value at that point in history **created\_at** `string` Date and time when the status was changed **account\_id** `integer` Identifier of the account linked after approval **created\_at** `string` Date and time when the account opening request was created **updated\_at** `string` Date and time when the request was last updated ## Request Example ```bash cURL theme={null} curl --request GET \ --url https://api.sandbox.wepayout.com.br/v2/register/companies/{id} \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_TOKEN' ``` ```javascript JavaScript theme={null} const id = '550e8400-e29b-41d4-a716-446655440000'; const response = await fetch( `https://api.wepayments.com/v2/register/companies/${id}`, { headers: { 'Accept': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN' } } ); const data = await response.json(); console.log(data); ``` ```python Python theme={null} import requests id = '550e8400-e29b-41d4-a716-446655440000' url = f'https://api.wepayments.com/v2/register/companies/{id}' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN' } response = requests.get(url, headers=headers) data = response.json() print(data) ``` ```json 200 OK theme={null} { "id": "550e8400-e29b-41d4-a716-446655440000", "company": { "legal_name": "Acme Tech LTDA", "trade_name": "Acme Tech", "tax_id": "11222333000181", "website": "https://www.acme.com", "contacts": [ { "name": "João Silva", "email": "joao@acme.com", "phone": "+5511999999999", "tax_id": "12345678901", "role": "administrator" }, { "name": "Maria Silva", "email": "maria.silva@acme.com", "phone": "+5511999999999", "tax_id": "12345678000", "role": "legal_representative" } ], "address": [ { "city": "São Paulo", "state": "SP", "country": "Brasil", "zip_code": "01234-567", "street": "Rua das Flores", "number": "123", "complement": "Sala 1" } ] }, "status": "active", "status_history": [ { "status": "pending", "created_at": "2024-01-01T10:00:00.000000Z" }, { "status": "due_diligence_review", "created_at": "2024-01-02T10:00:00.000000Z" }, { "status": "active", "created_at": "2024-01-03T10:00:00.000000Z" } ], "account_id": 999900, "created_at": "2024-01-01T10:00:00.000000Z", "updated_at": "2024-01-03T10:00:00.000000Z" } ``` ```json 404 Not Found theme={null} { "error": "Account opening request not found" } ``` # Get Balance Source: https://docs.wepayout.co/api-reference/account/get-balance GET /v2/account/{merchantId}/balance Check the balance of all the accounts you have access to ## Path Parameters **merchantId** `string` *required* Merchant ID ## Query Parameters **currency** `string` Currency code of your deposit account. If not provided, the default value will be DRE. Allowed values: `USD`, `AUD`, `EUR`, `GBP`, `BRL`, `CAD`, `CHF` Example: `BRL` **recipient\_id** `string` ID of your recipient Example: `12` ## Response This status is returned in the following scenarios: * The search was successful * When the currency is incorrectly provided, the return will have this status with zeroed values * When the merchant has no accounts, the return will have this status with zeroed values **balance** `number` Example: `12000` **available\_balance** `number` Example: `10000` **reserve\_balance** `number` Example: `0` **fee** `number or null` This field will only be different from null when the account is configured to receive fees in a wallet. Other than in this case, the balance of the other fee account(wallet) that will receive the fees is returned. Default: `null` Example: `100` ## Request Example ```bash cURL theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v2/account/{merchantId}/balance' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' ``` ```json 200 OK theme={null} { "balance": 10000, "available_balance": 10000, "reserve_balance": 0 } ``` ```json 500 Internal Server Error theme={null} { "error": "Internal server error" } ``` ## Response Fields ### balance The total balance in the account. ### available\_balance The balance available for withdrawal or transactions. ### reserve\_balance The amount held in reserve (if applicable). ### fee Fee balance (only applicable when the account is configured to receive fees in a wallet). ## Use Cases > [accordion] Check Available Funds > > Before processing a transaction, check if the merchant has sufficient available balance: > > ```javascript theme={null} > const balance = await getBalance(merchantId); > if (balance.available_balance >= transactionAmount) { > // Proceed with transaction > } else { > // Insufficient funds > } > ``` > [accordion] Multi-Currency Balance > > Check balances across different currencies: > > ```javascript theme={null} > const currencies = ['USD', 'BRL', 'EUR']; > const balances = await Promise.all( > currencies.map(currency => > getBalance(merchantId, { currency }) > ) > ); > ``` > [accordion] Monitor Reserve Balance > > Track the reserve balance to ensure compliance with reserve requirements: > > ```javascript theme={null} > const balance = await getBalance(merchantId); > if (balance.reserve_balance < requiredReserve) { > // Alert: Reserve below threshold > } > ``` ## Error Handling ### Invalid Currency When an invalid currency is provided, the API returns a 200 status with zeroed values: ```json theme={null} { "balance": 0, "available_balance": 0, "reserve_balance": 0 } ``` ### No Accounts When the merchant has no accounts, the API returns a 200 status with zeroed values: ```json theme={null} { "balance": 0, "available_balance": 0, "reserve_balance": 0 } ``` ## Best Practices > [!NOTE] > > **Cache Balance Data**: Balance information doesn't change frequently. Consider caching the response for a short period (e.g., 1-5 minutes) to reduce API calls. > [!WARNING] > > **Check Available Balance**: Always use `available_balance` rather than `balance` when determining if funds are available for transactions, as `balance` includes reserved amounts. # Get Balance Specific Day Source: https://docs.wepayout.co/api-reference/account/get-balance-specific-day GET /v2/account/{merchantId}/balance/history Check what the account balance was on a specific day ## Path Parameters **merchantId** `string` *required* Merchant ID ## Query Parameters **currency** `string` Currency code of your deposit account. If not provided, the default value will be DRE. Allowed values: `USD`, `AUD`, `EUR`, `GBP`, `BRL`, `CAD`, `CHF` Example: `BRL` **recipient\_id** `string` ID of your recipient Example: `12` **date** `string` *required* Enter the date in the following format: YYYY-MM-DD Example: `2024-01-15` ## Response **balance** `number` Example: `15000` **available\_balance** `number` Example: `10000` **reserve\_balance** `number` Example: `0` **fee** `number or null` This field will only be different from null when the account is configured to receive fees in a wallet. Other than in this case, the balance of the other fee account(wallet) that will receive the fees is returned. Default: `null` Example: `100` ## Request Example ```bash cURL theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v2/account/{merchantId}/balance/history'?date=2025-01-15 \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' ``` ```javascript JavaScript theme={null} const merchantId = 'your_merchant_id'; const date = '2024-01-15'; const response = await fetch( `https://api.wepayments.com/v2/account/${merchantId}/balance/history?date=${date}`, { headers: { 'Accept': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN' } } ); const data = await response.json(); console.log('Balance on', date, ':', data.balance); ``` ```python Python theme={null} import requests merchant_id = 'your_merchant_id' date = '2024-01-15' url = f'https://api.wepayments.com/v2/account/{merchant_id}/balance/history' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN' } params = {'date': date} response = requests.get(url, headers=headers, params=params) data = response.json() print(f"Balance on {date}: {data['balance']}") ``` ```json 200 OK theme={null} { "balance": 15000, "available_balance": 10000, "reserve_balance": 0, "fee": null } ``` ## Use Cases > [accordion] Historical Balance Tracking > > Track balance changes over time for reporting and reconciliation: > > ```javascript theme={null} > async function getBalanceHistory(merchantId, startDate, endDate) { > const dates = generateDateRange(startDate, endDate); > const history = []; > > for (const date of dates) { > const balance = await getBalanceSpecificDay(merchantId, date); > history.push({ date, ...balance }); > } > > return history; > } > ``` > [accordion] End-of-Day Reconciliation > > Verify end-of-day balances for accounting purposes: > > ```javascript theme={null} > async function reconcileEndOfDay(merchantId, date) { > const balance = await getBalanceSpecificDay(merchantId, date); > const transactions = await getTransactionsForDay(merchantId, date); > > // Compare calculated vs actual balance > const calculatedBalance = calculateBalance(transactions); > const difference = balance.balance - calculatedBalance; > > if (difference !== 0) { > console.warn(`Reconciliation mismatch: ${difference}`); > } > > return { balance, transactions, difference }; > } > ``` > [accordion] Financial Reporting > > Generate balance reports for specific periods: > > ```javascript theme={null} > async function generateMonthlyReport(merchantId, year, month) { > const daysInMonth = new Date(year, month, 0).getDate(); > const report = []; > > for (let day = 1; day <= daysInMonth; day++) { > const date = `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`; > const balance = await getBalanceSpecificDay(merchantId, date); > report.push({ date, balance: balance.balance }); > } > > return report; > } > ``` > [accordion] Audit Trail > > Create an audit trail of balance changes: > > ```javascript theme={null} > async function auditBalanceChanges(merchantId, dates) { > const audit = []; > > for (let i = 0; i < dates.length - 1; i++) { > const currentBalance = await getBalanceSpecificDay(merchantId, dates[i]); > const nextBalance = await getBalanceSpecificDay(merchantId, dates[i + 1]); > > const change = nextBalance.balance - currentBalance.balance; > > audit.push({ > date: dates[i], > balance: currentBalance.balance, > change: change, > percentChange: (change / currentBalance.balance) * 100 > }); > } > > return audit; > } > ``` ## Date Format The `date` parameter must be in the format `YYYY-MM-DD`: * ✅ Valid: `2024-01-15` * ✅ Valid: `2023-12-31` * ❌ Invalid: `15/01/2024` * ❌ Invalid: `01-15-2024` * ❌ Invalid: `2024/01/15` ## Response Fields ### balance The total balance in the account on the specified date. ### available\_balance The balance available for withdrawal or transactions on the specified date. ### reserve\_balance The amount held in reserve on the specified date (if applicable). ### fee Fee balance on the specified date (only applicable when the account is configured to receive fees in a wallet). ## Best Practices > [!NOTE] > > **Historical Data Availability**: Balance history is typically available for the past 90 days. Check with your account manager for specific data retention policies. > [!WARNING] > > **Rate Limiting**: When querying multiple dates, implement rate limiting to avoid hitting API limits. Consider batching requests or adding delays between calls. > [!TIP] > > **Caching**: Historical balance data doesn't change. Cache responses indefinitely to improve performance and reduce API calls. # Get Statement Source: https://docs.wepayout.co/api-reference/account/get-statement GET /v2/account/{merchantId}/statement Retrieve account statement with transaction history ## Path Parameters **merchantId** `string` *required* Merchant ID ## Query Parameters **id** `string` Specific statement ID **entity** `string` Filter by entity type Allowed values: `payout_merchant_note`, `payout_deposit`, `payout_transaction`, `payout_data_qualification`, `payin_transaction`, `payin_transaction_split`, `payin_transaction_creditcard`, `payin_transaction_creditcard_fee`, `payin_transaction_creditcard_split`, `payin_transaction_creditcard_installment`, `payin_transaction_creditcard_installment_fee`, `payin_transaction_creditcard_installment_split`, `payin_transaction_creditcard_installment_parent_split`, `payin_transaction_creditcard_parent_split_fee`, `payin_withdrawal`, `payin_transaction_refund`, `payin_transaction_rolling_reserve`, `payout_pix_reversal`, **category\_id** `string` Category IDs separated by comma Example: `1,8,9` **use\_for\_billing** `string` Filter by billing usage **created\_after** `string` Initial creation date (format: YYYY-MM-DD) Example: `2024-01-01` **created\_before** `string` Final creation date (format: YYYY-MM-DD) Example: `2024-01-31` **occurrence\_after** `string` Initial occurrence date (format: YYYY-MM-DD) Example: `2024-01-01` **occurrence\_before** `string` Final occurrence date (format: YYYY-MM-DD) Example: `2024-01-31` **recipient\_id** `string` Recipient ID **currency** `string` Currency Allowed values: `USD`, `AUD`, `EUR`, `BRL`, `GBP`, `CAD`, `CHF` > [!WARNING] > > **Required**: Must provide `created_after`/`created_before` OR `occurrence_after`/`occurrence_before` OR `id` **page** `integer` Page number **per\_page** `integer` Quantity of items per page ## Response Headers **x-next-page** `string` Next page number **x-page** `string` Current page number **x-per-page** `string` Total items per page **x-prev-page** `string` Previous page number **x-total** `string` Total count of records **x-value** `string` Boolean indicating if results exist **x-total-pages** `string` Total pages ## Response Body **array** `array` Array of statement entries **Statement Entry** **id** `integer` Statement ID **entity** `string` Entity type Possible values: `payout_merchant_note`, `payout_deposit`, `payout_transaction`, `payout_data_qualification`, `payin_transaction`, `payin_transaction_split`, `payin_transaction_creditcard`, `payin_transaction_creditcard_fee`, `payin_transaction_creditcard_split`, `payin_transaction_creditcard_installment`, `payin_transaction_creditcard_installment_fee`, `payin_transaction_creditcard_installment_split`, `payin_transaction_creditcard_installment_parent_split`, `payin_transaction_creditcard_parent_split_fee`, `payin_withdrawal`, `payin_transaction_refund`, `payin_transaction_rolling_reserve`, `payout_pix_reversal`, **entity\_id** `integer` Entity identifier **impact\_balance** `string` How transaction impacts balance (e.g., `available`, `reserve`, `both`) **category** `object` Category information **Category** **id** `integer | null` Category ID **name** `string` Category name **amount** `number` Transaction amount (positive for credit, negative for debit) **available\_balance** `number | null` Available balance after transaction **balance** `number | null` Total balance after transaction **reserve\_balance** `number | null` Reserve balance after transaction **invoice** `string | null` Invoice reference **description** `string | null` Transaction description **occurrence\_at** `string` When the transaction occurred (ISO 8601 format) **created\_at** `string` When the statement entry was created (ISO 8601 format) ```json 200 OK theme={null} [ { "id": 12345, "entity": "payin_transaction", "entity_id": 67890, "impact_balance": "available", "category": { "id": 1, "name": "PIX Payment" }, "amount": 100.50, "available_balance": 1500.00, "balance": 1500.00, "reserve_balance": 0.00, "invoice": "INV-12345", "description": "Payment received", "occurrence_at": "2024-01-15T10:30:00-03:00", "created_at": "2024-01-15T10:30:00-03:00" }, { "id": 12346, "entity": "payin_transaction_creditcard_fee", "entity_id": 67890, "impact_balance": "available", "category": { "id": 8, "name": "PIX Fee" }, "amount": -2.50, "available_balance": 1497.50, "balance": 1497.50, "reserve_balance": 0.00, "invoice": null, "description": "PIX transaction fee", "occurrence_at": "2024-01-15T10:30:00-03:00", "created_at": "2024-01-15T10:30:00-03:00" } ] ``` ```json 400 Bad Request theme={null} { "error": "Invalid parameters" } ``` ```json 500 Internal Server Error theme={null} { "error": "Internal server error" } ``` ## Transaction Categories The statement includes various transaction categories. Use the category ID when filtering: | ID | Name | Description | | - | - | - | | 1 | PIX Payment | PIX payment received | | 2 | PIX Reversal | PIX payment reversal | | 3 | TED Payment | TED transfer payment | | 4 | TED Reversal | TED transfer reversal | | 5 | Transfer Between WE Accounts | Internal transfers between WE accounts | | 6 | Transfer | General transfers | | 7 | Boleto Payment | Boleto payment received | | 8 | PIX Fee | PIX transaction fee | | 9 | Boleto Fee | Boleto transaction fee | | 10 | TED Fee | TED transfer fee | | 11 | Merchant Note Settlement | Settlement entry | | 12 | Merchant Note Tax | Tax entry | | 13 | Merchant Note Generic | Generic merchant note | | 14 | Transfer Fee | Transfer transaction fee | | 15 | Others | Other transactions | | 16 | Rolling Reserve | Rolling reserve | | 17 | Credit Card Transaction | Credit card payment | | 18 | Credit Card Fee | Credit card fee | | 51 | Merchant Note Judicial Freeze | Judicial freeze | | 52 | PIX Refund | PIX refund | | 53 | Markup | Markup fee | | 54 | Current Balance | Current balance | | 55 | Conversion Fee | Conversion Fee | **Example**: To filter PIX-related transactions (payments and fees), use: `?category_id=1,8` # List Account Opening Requests Source: https://docs.wepayout.co/api-reference/account/list-accounts GET /v2/register/companies Retrieves a list of all account opening requests submitted through the registration process. ## Query Parameters **created\_after** `string` Filters results to include only account opening requests created after the specified date. Example: `2025-10-01` **created\_before** `string` Filters results to include only account opening requests created before the specified date. Example: `2025-10-20` **status** `string` Filters account opening requests by their current status. The accepted values are listed in the status enum section below. Allowed values: `active`, `canceled`, `closed`, `due_diligence_review`, `inactive`, `pending` **updated\_after** `string` Filters results to include only account opening requests updated after the specified date. Example: `2025-10-15` **updated\_before** `string` Filters results to include only account opening requests updated before the specified date. Example: `2025-10-28` ## Response Body **array** `array` Array of account opening requests **Request Object** **id** `string` Unique identifier of the account opening request **company** `object` Company information **Company Details** **legal\_name** `string` Company’s registered legal name **trade\_name** `string` Company’s trade name or business name **tax\_id** `string` Company’s tax identification number (CNPJ), without separators. The first 12 characters may be digits or uppercase letters; the last 2 are always numeric check digits. **website** `string` Company’s website, as sent on the solicitation. `null` for solicitations created before this field existed **contacts** `array` List of contact persons associated with the company. Each object represents a contact. **Contact** **name** `string` Full name of the contact person **email** `string` Email address of the contact person **phone** `string` Phone number including country and area code **tax\_id** `string` Contact’s individual tax ID (CPF), numbers only **role** `string` Role within the company Allowed values: `administrator`, `legal_representative`, `financial`, `commercial`, `compliance` **address** `array` List of company addresses **Address** **city** `string` City name **state** `string` State abbreviation (UF) **country** `string` ISO 3166-1 alpha-2 country code **zip\_code** `string` Postal code (CEP), numbers only **street** `string` Street or public place name **number** `string` Address number **complement** `string` Address complement, if any **status** `string` Current status Values: `pending`, `due_diligence_review`, `active`, `inactive`, `canceled`, `closed` **status\_history** `array` History of status changes **Status History** **status** `string` Status value at that point **created\_at** `string` Timestamp of the status change **account\_id** `integer` ID of the account linked after approval **created\_at** `string` Timestamp when the request was created **updated\_at** `string` Timestamp when the request was last updated ```json 200 OK theme={null} [ { "id": "a1b2c3d4-e5f6-4789-801a-bcdef1234567", "company": { "legal_name": "Example Fictitious Corp", "trade_name": "Fictitious Solutions", "tax_id": "11111111000111", "website": "https://www.fictitious-solutions.com", "contacts": [ { "name": "John Doe", "email": "john.doe@example.com", "phone": "5511999999999", "tax_id": "12345678901", "role": "administrator" }, { "name": "Jane Smith", "email": "jane.smith@example.com", "phone": "5511988888888", "tax_id": "98765432100", "role": "legal_representative" } ], "address": [ { "city": "Example City", "state": "EX", "country": "BR", "zip_code": "00000000", "street": "Fictional Avenue", "number": "100", "complement": "Suite 101" } ] }, "status": "active", "status_history": [ { "status": "pending", "created_at": "2025-10-02T13:34:38.000Z" }, { "status": "due_diligence_review", "created_at": "2025-10-03T09:15:12.000Z" } ], "account_id": 1001000, "created_at": "2025-10-02T13:34:05.000Z", "updated_at": "2025-10-03T10:22:44.000Z" } ] ``` # List Merchant Pix Keys Source: https://docs.wepayout.co/api-reference/account/pix-keys/list-pix-keys GET /v2/register/pix-keys Consolidated list of the Pix keys of a merchant and its submerchants, with search filters and result counters. Read-only. > [!NOTE] > > Returns **one row per account** — the merchant identified by `we_id` plus every submerchant registered under it — together with the Pix key held by that account. There is **no pagination**: the response always covers the whole hierarchy, and the filters narrow down the rows that are returned. > > Accounts with no Pix key are **not** listed. A merchant with no eligible account still answers `200` with an empty `data` array and zeroed counters — never `404`. ## Query Parameters **we\_id** `integer` *required* WE ID of the merchant whose hierarchy is listed. The response covers this merchant **and** its submerchants. Must be within the scope of the authenticated credentials, otherwise the request is rejected with `403`. Example: `1020100` **merchant\_id** `string` Narrows the result down to the accounts whose WE ID **starts with** the supplied value, so the search box of a panel filters the list while the ID is being typed. Digits only, up to 20 characters. `10201` matches `1020101`; `0101` does **not**. Example: `1020101` **name** `string` Narrows the result down to the accounts whose company name **contains** the supplied value. Case and accent insensitive: `jose` matches `JOSÉ`. Up to 150 characters. Example: `retail` **document** `string` Narrows the result down to the accounts whose company document **contains** the supplied digits. Both sides are compared digits only, so a mask is accepted: `34.881.207/0001-46`, `34881207000146` and `34881` all match the same account. Up to 20 characters. A value with no digit at all is treated as no filter, instead of matching everything. Example: `34.881` **status** `string` (default: active) Status of the Pix key. Applied by default even when omitted, so a request with no `status` returns the active keys. Allowed values: `active` This is currently the only accepted value — any other value is rejected with `422`. Consequently, `pix_key.status` always comes back as `ACTIVE`. > [!NOTE] > > Filters are combined with **AND**: an account is returned only when it satisfies every supplied filter. ## Response **summary** `object` Counters of the listing, meant to feed a "X of Y accounts" label. **summary object** **total\_accounts** `integer` Number of accounts in the hierarchy holding a Pix key, **before** the `merchant_id`, `name` and `document` filters. This is the denominator: an account with no key is neither listed nor counted. **filtered** `integer` Number of accounts left **after** every filter. Always equal to the length of `data`. **data** `array` Accounts and their Pix keys. The queried merchant always comes first, followed by the submerchants ordered by ascending WE ID. **account object** **merchant\_id** `integer` WE ID of the account. **is\_main** `boolean` `true` on the merchant supplied as `we_id`, `false` on its submerchants. Lets the client render the main account apart without comparing IDs. **name** `string` Legal name of the **company** that owns the account. **document** `string` Document (CNPJ) of the **company** that owns the account, digits only. **pix\_key** `object` The Pix key held by the account. **pix\_key object** **key** `string` Value of the Pix key, as registered at the DICT. **type** `string` Type of the key. Values: `CPF`, `CNPJ`, `EVP`, `EMAIL`, `PHONE` **status** `string` Status of the key, reported in upper case. Values: `ACTIVE` **owner\_name** `string` Name of the Pix key holder registered at the DICT. **owner\_document** `string` Document of the Pix key holder registered at the DICT, digits only. **ispb** `string` ISPB of the institution holding the key. Always `32708748` (WEpayments). **bank\_name** `string` Name of the institution holding the key. Always `WEpayments`. **created\_at** `string | null` When the key was created. ISO 8601 with offset. `null` when the date is unknown. ```json 200 OK theme={null} { "summary": { "total_accounts": 3, "filtered": 3 }, "data": [ { "merchant_id": 1020100, "is_main": true, "name": "Example Fictitious Corp", "document": "11111111000111", "pix_key": { "key": "a3f1c8e2-0000-4000-8000-000000000000", "type": "EVP", "status": "ACTIVE", "owner_name": "Example Fictitious Corp", "owner_document": "11111111000111", "ispb": "32708748", "bank_name": "WEpayments", "created_at": "2025-03-01T10:00:00-03:00" } }, { "merchant_id": 1020101, "is_main": false, "name": "Fictitious Retail Ltda", "document": "22222222000122", "pix_key": { "key": "22222222000122", "type": "CNPJ", "status": "ACTIVE", "owner_name": "Fictitious Retail Ltda", "owner_document": "22222222000122", "ispb": "32708748", "bank_name": "WEpayments", "created_at": "2025-04-12T09:31:20-03:00" } }, { "merchant_id": 1020102, "is_main": false, "name": "Fictitious Cross Border Ltda", "document": "33333333000133", "pix_key": { "key": "b7d4e5a1-1111-4111-8111-111111111111", "type": "EVP", "status": "ACTIVE", "owner_name": "WE PAY OUT INSTITUICAO DE PAGAMENTO LTDA", "owner_document": "32708748000130", "ispb": "32708748", "bank_name": "WEpayments", "created_at": "2025-06-20T14:05:00-03:00" } } ] } ``` ```json 200 Empty result theme={null} { "summary": { "total_accounts": 0, "filtered": 0 }, "data": [] } ``` ```json 401 Unauthenticated theme={null} { "error_code": "authentication", "error_description": "Unauthenticated." } ``` ```json 403 Access denied theme={null} { "message": "You are not allowed to access this merchant" } ``` ```json 422 Validation error theme={null} { "error_code": "validation", "error_description": "Validation error", "fields": { "we_id": [ "The we id field is required." ] } } ``` ```json 502 Upstream unavailable theme={null} { "message": "Could not retrieve the Pix keys right now" } ``` ## Errors | Status | When | | - | - | | `401` | Missing or invalid credentials. | | `403` | `we_id` is outside the scope of the authenticated credentials. The message is deliberately generic and never discloses whether the merchant exists. | | `422` | `we_id` is missing or not a positive integer, or a filter does not match its expected format. | | `502` | The Pix keys could not be retrieved from the upstream service. Retry — this never means the merchant has no keys. | | `400` | Unexpected error while listing the keys. | > [!NOTE] > > Because the response depends on the scope of the caller, it is **never cached** at the gateway. Two different credentials asking for the same `we_id` may legitimately receive different results. ## Example request ```bash cURL theme={null} curl -X GET "https://api.sandbox.wepayout.com.br/v2/register/pix-keys?we_id=1020100&merchant_id=10201" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" ``` ## Related Resources > [card] [List Account Opening Requests](/api-reference/account/list-accounts) > > Find the WE IDs of the accounts in your hierarchy > [card] [Create Company](/api-reference/account/create) > > Register a new submerchant # List Segments Source: https://docs.wepayout.co/api-reference/account/segments/list-segments GET /v2/register/segments List all segments or retrieve a single segment by ID > [!NOTE] > > Segments are a small, closed set of values accepted by WE, so this endpoint returns **all** of them in a single response — there is **no pagination**. > > Provide the optional `id` query parameter to filter by a specific segment. The response is **always an array**, even when filtering by `id` (it returns an array containing a single item). > [!NOTE] > > The `name` field is localized based on the authenticated user's locale: when the locale is English (`en`), the English name is returned, falling back to the default name when no translation is available. ## Query Parameters **id** `integer` The ID of the segment to retrieve. When provided, the response contains only the matching segment (as a single-item array). ## Response **Response** `array` List of segments **segment object** **id** `integer` Unique identifier of the segment. **name** `string` Name of the segment, localized according to the authenticated user's locale. ```json 200 theme={null} [ { "id": 1, "name": "Banking" }, { "id": 2, "name": "Retail" } ] ``` ```json 404 theme={null} { "message": "Segment not found" } ``` ```json 400 theme={null} { "message": "Error listing segments" } ``` # Get Signature Link Source: https://docs.wepayout.co/api-reference/account/signature/signature-link GET /v2/register/companies/{uuid}/signature/link Retrieve the contract signing links for each legal representative of a solicitation. Applies to the national onboarding flow, when the solicitation is in waiting_signature. > [!NOTE] > > Part of the [Onboarding Documents flow](/account/onboarding-documents-flow). After compliance approves all documents in a **national** solicitation, its status becomes `waiting_signature` and a contract is issued for signature (via ZapSign). Use this endpoint to get each signer's `sign_url` and route the legal representatives to sign. > > **Cross-border** solicitations have no signature step — calling this endpoint for one returns `404`. ## Path Parameters **uuid** `string` *required* UUID of the solicitation (the `id` returned by [Create Company](/api-reference/account/create)). * Format: UUID * Example: `339074a8-1834-49c5-af94-4a044248d88d` ## Response **status** `string` Status of the signature request. One of `pending_signature`, `signed`, `expired`. **signers** `array` The legal representatives who must sign the contract. **signer object** **name** `string` Signer's full name. **email** `string` Signer's email address. **status** `string` Signing status of this signer. One of `pending`, `signed`. **sign\_url** `string` The ZapSign signing link. Route the signer to this URL to sign the contract. ```json 200 OK theme={null} { "status": "pending_signature", "signers": [ { "name": "João Silva", "email": "joao.silva@companyx.com", "status": "pending", "sign_url": "https://app.zapsign.com.br/verificar/doc/xxxxxxxx" } ] } ``` ```json 404 Signature not found theme={null} { "message": "Signature request not found" } ``` ```json 404 Solicitation not found theme={null} { "message": "Solicitation not found" } ``` ## Errors | Status | When | | - | - | | `404` | Solicitation not found / not accessible, or the solicitation has no signature request (e.g. a cross-border solicitation, or one that has not reached `waiting_signature`). | ## Download the signed contract To download the contract document (the original, or the signed version once available), call: ``` GET /v2/register/companies/{uuid}/signature/file ``` The response streams the file as a binary download (with its original file name). | Status | When | | - | - | | `200` | File returned as a download. | | `404` | Solicitation not found, or no signature document file available. | ```bash cURL theme={null} curl -X GET "https://api.sandbox.wepayout.com.br/v2/register/companies/339074a8-1834-49c5-af94-4a044248d88d/signature/file" \ -H "Authorization: Bearer YOUR_API_KEY" \ -o contract.pdf ``` ## Examples ```bash cURL theme={null} curl -X GET "https://api.sandbox.wepayout.com.br/v2/register/companies/339074a8-1834-49c5-af94-4a044248d88d/signature/link" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.sandbox.wepayout.com.br/v2/register/companies/339074a8-1834-49c5-af94-4a044248d88d/signature/link", { headers: { Authorization: "Bearer YOUR_API_KEY" } } ); const { signers } = await response.json(); signers.forEach((s) => console.log(`${s.name}: ${s.sign_url}`)); ``` ```python Python theme={null} import requests url = "https://api.sandbox.wepayout.com.br/v2/register/companies/339074a8-1834-49c5-af94-4a044248d88d/signature/link" headers = {"Authorization": "Bearer YOUR_API_KEY"} response = requests.get(url, headers=headers) for signer in response.json()["signers"]: print(signer["name"], signer["sign_url"]) ``` ## Related Resources > [card] [Onboarding Documents Integration](/account/onboarding-documents-flow) > > Understand the full flow > [card] [Onboarding Webhook](/api-reference/account/webhook/onboarding-documents) > > Statuses delivered to your URL # Onboarding Documents Flow Source: https://docs.wepayout.co/api-reference/account/webhook/onboarding-documents New onboarding flow that requests, via webhook, the documents required for the company segment and modality. > [!NOTE] > > This flow is rolled out **per merchant** through a feature flag — **off by default**. It only applies when the company is created with a **segment** (see [Create Company](/api-reference/account/create) and [List Segments](/api-reference/account/segments/list-segments)). > > Merchants without the flag enabled continue on the legacy onboarding flow. > > For the full integration walkthrough, see [Onboarding Documents Integration](/account/onboarding-documents-flow). ## Status Flow When a company is created with a segment, it is moved to **`pending_documents`** and the onboarding webhook delivers the list of documents the client must send. Once **all required** documents are sent, the solicitation advances to `documents_under_review`. After compliance approves every document, the flow **branches by modality** (derived from the company address country): * **National** (address in Brazil): the solicitation moves to `waiting_signature` while the legal representatives sign the contract; once signed, the account is created and becomes `active`. * **Cross-border** (address outside Brazil): the solicitation moves to `waiting_bank_channel`, then to `bank_channel_in_progress` while the bank channel is being opened, to `bank_channel_created` once it is opened, and finally to `active`. There is **no signature step** for cross-border. A rejection sends the solicitation back to `pending_documents`, and a closed review moves it to `canceled`. This flow does **not** go through `due_diligence_review` (that step only exists in the legacy flow). ```mermaid theme={null} graph LR A[pending] --> B[pending_documents] B --> C[documents_under_review] C -->|rejection| B C -->|close| E[canceled] C -->|national| S[waiting_signature] C -->|cross-border| K[waiting_bank_channel] S -->|signed| D[active] K --> P[bank_channel_in_progress] P --> L[bank_channel_created] L --> D[active] D --> F[inactive] D --> G[closed] style A fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#000 style B fill:#ede9fe,stroke:#8b5cf6,stroke-width:2px,color:#000 style C fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#000 style S fill:#ffedd5,stroke:#f97316,stroke-width:2px,color:#000 style K fill:#cffafe,stroke:#06b6d4,stroke-width:2px,color:#000 style P fill:#cffafe,stroke:#06b6d4,stroke-width:2px,color:#000 style L fill:#ccfbf1,stroke:#14b8a6,stroke-width:2px,color:#000 style D fill:#d1fae5,stroke:#10b981,stroke-width:2px,color:#000 style E fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#000 style F fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#000 style G fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#000 ``` ## Statuses ### `pending` First status of the process. The account opening request has been received and is awaiting processing. ### `pending_documents` The documents required for the company's **segment** and **modality** (national/crossborder) were resolved and attached to the onboarding request. The webhook for this status includes the list of `documents` the client must send (see [Webhook Payload](#webhook-payload)). The solicitation stays here until **all required** documents are sent; optional documents do not block the transition. ### `documents_under_review` All required documents were sent and compliance is reviewing them. The webhook payload still includes the `documents` list, now carrying each document's review state. A rejection sends the solicitation back to `pending_documents` (preserving already-approved documents); once everything is approved the flow branches by modality (`waiting_signature` for national, `waiting_bank_channel` for cross-border). ### `waiting_signature` **National only.** All documents were approved and the contract is awaiting signature by the legal representatives. Fetch the signing links with the [Get Signature Link](/api-reference/account/signature/signature-link) endpoint and route each representative to their `sign_url`. Once every signer has signed, the account is created and the solicitation moves to `active`. The webhook payload for this status does **not** include the `documents` array. ### `waiting_bank_channel` **Cross-border only.** All documents were approved and the bank channel opening was requested; it is waiting for WEpayments to start it. The webhook payload for this status does **not** include the `documents` array. ### `bank_channel_in_progress` **Cross-border only.** WEpayments is opening the bank channel. The solicitation moves to `bank_channel_created` once the channel is opened. The webhook payload for this status does **not** include the `documents` array. ### `bank_channel_created` **Cross-border only.** The bank channel was created; the account is being finalized and will move to `active`. The webhook payload for this status does **not** include the `documents` array. ### `active` Account is active/approved. At this status, the webhook sends the `account_id` (MID - Merchant ID) that identifies the merchant's account. ### `canceled` Onboarding did not proceed — compliance closed the solicitation. The webhook payload includes the `documents` list and a top-level `reason` object identifying why it was closed. ### `inactive` Account is inactive after being previously activated. ### `closed` Account has been closed. ## Webhook Payload The payload always carries the solicitation `id`, its `status` and `updated_at`. The `documents` array is included while the solicitation is in `pending_documents`, `documents_under_review` or `canceled`, and a `reason` object is included when `status` is `canceled`: ```json theme={null} { "id": "1234-5678-90ab-cdef-1234567890ab", "status": "pending_documents", "updated_at": "2024-01-15T10:30:00.000000Z", "account_id": null, "documents": [ { "name": "Articles of Incorporation", "tag": "articles_of_incorporation", "description": "Company's current articles of incorporation", "required": true, "upload_status": "pending", "review_status": "pending" } ] } ``` When the solicitation is closed, the same payload carries the `reason` object: ```json theme={null} { "id": "1234-5678-90ab-cdef-1234567890ab", "status": "canceled", "updated_at": "2024-01-15T10:30:00.000000Z", "account_id": null, "reason": { "code": "no_customer_response", "detail": "No response from the client" }, "documents": [ { "name": "Articles of Incorporation", "tag": "articles_of_incorporation", "description": "Company's current articles of incorporation", "required": true, "upload_status": "sent", "review_status": "rejected", "reason": "No response from the client" } ] } ``` **id** `string` UUID of the solicitation. **status** `string` Current status of the solicitation. **updated\_at** `string` Timestamp of the last status change (ISO 8601). **account\_id** `string | null` The merchant account identifier (MID). `null` until the account is created — populated when `status` is `active`. **reason** `object` Why the solicitation was closed. Present only when `status` is `canceled`. **reason object** **code** `string` Identifier of the closure reason, from a closed catalogue. One of `restriction_list`, `segment_not_allowed`, `duplicate_request`, `no_customer_response`, `customer_withdrawal`, `other`. This is the stable value — integrate against it rather than against `detail`. **detail** `string` Standardised description of the `code`, in English. Provided for convenience; the wording may be revised, so do not branch your logic on it. **documents** `array` List of documents required for the company, resolved from its segment and modality. Present when `status` is `pending_documents`, `documents_under_review` or `canceled`. **document object** **name** `string` Human-readable name of the document. **tag** `string` Machine-readable identifier of the document type — the value used to upload it. **description** `string` Description of what the document is. **required** `boolean` Whether the document is mandatory for the onboarding to proceed. **upload\_status** `string` Upload state, owned by the client. One of `pending`, `sent`. **review\_status** `string` Compliance review state. One of `pending`, `approved`, `rejected`. **reason** `string` Why this document was rejected. Present only when `review_status` is `rejected`. Not to be confused with the top-level `reason` object, which explains why the whole solicitation was closed — on a closure every document carries the closure text here. > [!NOTE] > > **When is it fired?** A webhook is dispatched on every status change, on every document upload, and on every compliance decision — so expect multiple deliveries per solicitation. Reconcile by `id` + `status` and the per-document state, and keep your handler idempotent. > [!NOTE] > > **Delivery & retries:** your webhook endpoint must return a `200 OK` status code to acknowledge receipt. If it fails or returns an error, delivery is retried **up to 3 times, every 15 minutes**. > [!NOTE] > > To receive onboarding status updates via webhook, register them using the [Webhook Setup](/api-reference/account/webhook/webhook-setup) endpoint. # Query Source: https://docs.wepayout.co/api-reference/account/webhook/webhook-query GET /v2/register/companies/webhooks Query the registered webhook URLs # Query This endpoint allows querying the registered webhook URLs and the events each one receives. Filtering can only be done by account. * If `account_id` is provided, only the webhooks of that account will be returned * If `account_id` is omitted, the webhooks of your merchant **and of all its subaccounts** will be returned, ordered by account ## Query Parameters **account\_id** `integer` ID of the account whose webhooks will be returned: your own merchant or one of its subaccounts. When omitted, the response includes the webhooks of your merchant and of every subaccount you have access to. If the account does not exist or is not linked to your merchant, the request fails with `422` and the `invalid_account` code. Example: `4521` ## Response Returns an array of webhook objects. > [!TIP] > > The same URL can be registered on your merchant and on each subaccount, so a webhook is identified by the pair `account_id` + `url`. To [update](/api-reference/account/webhook/webhook-update) or [remove](/api-reference/account/webhook/webhook-remove) a webhook returned here, send the same `account_id` along with the `url`. > [!NOTE] > > Only the webhooks registered on each account are listed. A subaccount without its own webhook for an event uses the main account's webhook for that event, which appears only under the main account. See [Subaccounts without a webhook](/api-reference/account/webhook/webhook-setup#subaccounts-without-a-webhook). **array** `array` Array of webhook objects **Webhook Object** **account\_id** `integer` ID of the account the webhook belongs to: your merchant or one of its subaccounts Example: `1234` **events** `string[]` Events the webhook receives Example: `["payin", "payout"]` **url** `string` HTTPS endpoint URL that receives the notifications of every event in `events` Example: `https://my-url.requestcatcher.com/test` **secret** `string` Secret used to sign the webhooks delivered to this URL with [HMAC-SHA256](/concepts/webhooks#hmac-sha256-signature), or `null` if none is set Example: `whsec_9f8e7d6c5b4a3210` ## Request Example ```bash cURL theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' ``` ```javascript JavaScript theme={null} const response = await fetch('https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks', { method: 'GET', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN' } }); const data = await response.json(); console.log(data); ``` ```python Python theme={null} import requests url = 'https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN' } response = requests.get(url, headers=headers) print(response.json()) ``` ```bash cURL (single account) theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks?account_id=4521' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' ``` ```json 200 OK theme={null} [ { "account_id": 1234, "events": ["onboarding"], "url": "https://my-url.requestcatcher.com/test", "secret": null }, { "account_id": 1234, "events": ["payin", "payout", "kyc"], "url": "https://my-url.requestcatcher.com/transactions", "secret": "whsec_9f8e7d6c5b4a3210" }, { "account_id": 4521, "events": ["payin"], "url": "https://subaccount.requestcatcher.com/payin", "secret": null } ] ``` ```json 422 Unprocessable Entity theme={null} { "error_code": "validation", "error_description": "Validation error", "fields": { "account_id": ["The account does not exist or is not linked to your merchant."] }, "field_errors": [ { "field": "account_id", "code": "invalid_account", "params": [], "message": "The account does not exist or is not linked to your merchant." } ] } ``` # Remove Source: https://docs.wepayout.co/api-reference/account/webhook/webhook-remove DELETE /v2/register/companies/webhooks Remove a registered webhook # Remove Webhook URL This endpoint allows removing a registered webhook URL, together with **every event** it receives. * The webhook is identified by its `url` and the optional `account_id`, both sent in the request body. The path never carries the URL * To stop a single event and keep the others, use [Update](/api-reference/account/webhook/webhook-update) and send `events` without it * Once deleted, none of the webhook's events are sent to the URL anymore. Each event then goes to the next destination: * On a subaccount, the main account's webhook for that event, if there is one (`payin`, `payout` and `kyc` — see [Subaccounts without a webhook](/api-reference/account/webhook/webhook-setup#subaccounts-without-a-webhook)) * Otherwise, for `payin` and `payout`, the `notification_url` of each transaction, signed with the deprecated API key signature (see [Webhook Signature](/concepts/webhooks)); for `kyc`, the KYC callback URL previously configured by our Customer Experience team, if any, without the `x-webhook-wp-*` headers (see [KYC Webhook](/api-reference/kyc/webhook)) > [!WARNING] > > Registering, updating or removing a webhook may take up to **5 minutes** to take effect. Until then, webhooks keep being delivered to the previous destination. ## Request Body **url** `string` *required* URL of the webhook that will be removed. Together with `account_id`, it identifies the webhook. Example: `https://my-url.requestcatcher.com/test` **account\_id** `integer` ID of the account whose webhook will be removed: your own merchant or one of its subaccounts. When omitted, the webhook of **your merchant** (the authenticated account) is removed. If the account does not exist or is not linked to your merchant, the request fails with `422` and the `invalid_account` code. If the account has no webhook with this URL, the request fails with `404`. Example: `4521` > [!WARNING] > > Without `account_id`, the removal always targets **your merchant**, even if the webhook you want to remove was listed by [Query](/api-reference/account/webhook/webhook-query) under a subaccount. Send the `account_id` returned with the webhook to remove the right one. ## Response Returns **200 OK** with a confirmation message on successful deletion. **message** `string` Confirmation message. Example: `Webhook deleted successfully` ## Request Example ```bash cURL theme={null} curl --request DELETE \ --url https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks \ --header 'Authorization: Bearer {token}' \ --header 'Content-Type: application/json' \ --data '{ "account_id": 4521, "url": "https://my-url.requestcatcher.com/test" }' ``` ```javascript JavaScript theme={null} const response = await fetch('https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks', { method: 'DELETE', headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ account_id: 4521, url: 'https://my-url.requestcatcher.com/test' }) }); if (response.status === 200) { console.log('Webhook removed successfully'); } ``` ```python Python theme={null} import requests url = 'https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks' headers = { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' } data = { 'account_id': 4521, 'url': 'https://my-url.requestcatcher.com/test' } response = requests.delete(url, json=data, headers=headers) if response.status_code == 200: print('Webhook removed successfully') ``` ```json 200 OK theme={null} { "message": "Webhook deleted successfully" } ``` ```json 404 Not Found theme={null} { "message": "Webhook not found." } ``` ```json 422 Unprocessable Entity theme={null} { "error_code": "validation", "error_description": "Validation error", "fields": { "account_id": ["The account does not exist or is not linked to your merchant."] }, "field_errors": [ { "field": "account_id", "code": "invalid_account", "params": [], "message": "The account does not exist or is not linked to your merchant." } ] } ``` # Setup Source: https://docs.wepayout.co/api-reference/account/webhook/webhook-setup POST /v2/register/companies/webhooks Register a webhook URL and the events it receives # Setup The system allows the registration of webhook URLs to receive automatic notifications about relevant events. A webhook is **one URL that receives one or more events**: send every event the URL should receive in the `events` list. **Webhook URL:** HTTPS address where the events will be delivered.\ **Supported events:** onboarding, payin, payout, kyc\ **Notification format:** JSON payload sent via HTTP request\ **Request method:** All notifications will be sent exclusively using the POST method > [!CAUTION] > > **The registered URL overrides the URL sent in each request.** Once a webhook is registered for the `payin` or `payout` event, **every** webhook of that event is delivered to the registered URL, and the `notification_url` / `callback_url` sent when creating a transaction is **ignored**. The same applies to all Payin and Payout webhooks — status updates, refunds and Data Qualifications. The URL sent in the request is only used when no webhook is registered for the event. > > For the `kyc` event, the registered URL replaces the KYC callback URL previously configured by our Customer Experience team. > > Registered deliveries are sent with the `x-webhook-wp-type` and `x-webhook-wp-timestamp` headers (plus `x-webhook-wp-signature` when a `secret` is set). See [Webhook Signature](/concepts/webhooks). > [!WARNING] > > Registering, updating or removing a webhook may take up to **5 minutes** to take effect. Until then, webhooks keep being delivered to the previous destination. ## Subaccounts without a webhook > [!WARNING] > > **A subaccount without its own webhook uses the webhook of its main account.** For the `payin`, `payout` and `kyc` events, when a subaccount has no webhook registered for the event, its notifications are delivered to the webhook its **main account** registered for that same event — to the main account's URL, signed with the main account's `secret`. > > * The fallback is decided **per event**: a subaccount with its own `payin` webhook and no `payout` webhook receives `payin` on its own URL and `payout` on the main account's. > * Only when neither the subaccount nor its main account has a webhook for the event are the notifications sent to the transaction's `notification_url` (`payin` and `payout`) or to the KYC callback URL configured by our Customer Experience team (`kyc`). > * The `onboarding` event has no fallback: it is always delivered to the `onboarding` webhook of the account that requested the onboarding. > > To send a subaccount's notifications somewhere else, register a webhook for it with `account_id`. ## Request Body **events** `string[]` *required* Events this webhook will receive. Send at least one event, without repeating any. Allowed values: `onboarding`, `payin`, `payout`, `kyc` * `onboarding`: notifications about the account onboarding status. Sent without the `x-webhook-wp-type` header. * `payin`: notifications about Payin status changes (Pix — including Pix key credits and Automatic Pix —, Boleto, Credit Card and refunds). `x-webhook-wp-type` values: * `payin-pix`: status update of a Pix Payin (including Automatic Pix and Pix key credits) * `payin-boleto`: status update of a Boleto Payin * `payin-credit-card`: status update of a Credit Card Payin * `payin-refund`: refund of a received Pix Payin, requested by the merchant * `payout`: notifications about Payout status changes, refunds and Data Qualifications. `x-webhook-wp-type` values: * `payout-pix`: status update of a Pix Payout * `payout-ted`: status update of a TED Payout * `payout-qrcode`: status update of a Pix QR Code Payout * `payout-refund`: Pix Payout returned to the merchant * `payout-customer-refund`: status update of a customer refund (Reembolso) paid out to your customer * `payout-data-qualification`: status update of a Data Qualification * `kyc`: notifications about KYC status changes. See [KYC Webhook](/api-reference/kyc/webhook). `x-webhook-wp-type` value: * `kyc`: status update of a KYC See [Webhook types](/concepts/webhooks#webhook-types) for details. Each event can be on **only one webhook per account**: the same event can be registered on your merchant and on each of its subaccounts, but not on two URLs of the same account. Sending an event that another webhook of the target account already receives fails with `422` and the `webhook_already_exists` code on that item (for example `events.1`) — move the event with [Update](/api-reference/account/webhook/webhook-update) instead. Example: `["payin", "payout"]` **url** `string` *required* Endpoint URL that will receive the notifications of every event in `events`. The URL identifies the webhook: use it to [update](/api-reference/account/webhook/webhook-update) or [remove](/api-reference/account/webhook/webhook-remove) the webhook later. Each URL can be registered **only once per account** (URLs that differ only in letter case count as the same URL). Registering a URL that the target account already has fails with `422` and the `webhook_url_already_exists` code — add the new events to the existing webhook with [Update](/api-reference/account/webhook/webhook-update) instead. Maximum length: 120 characters Example: `https://my-url.com/test` **secret** `string` Secret used to sign the `payin`, `payout` and `kyc` webhooks with [HMAC-SHA256](/concepts/webhooks#hmac-sha256-signature). When provided, every webhook delivered to this URL includes the `x-webhook-wp-signature` header. Maximum length: 255 characters. Use a long, randomly generated value. Example: `whsec_9f8e7d6c5b4a3210` **account\_id** `integer` ID of the account the webhook will be registered for: your own merchant or one of its subaccounts. Use it to register the webhooks of a subaccount with your own credentials. When omitted, the webhook is registered for **your merchant** (the authenticated account). If the account does not exist or is not linked to your merchant, the request fails with `422` and the `invalid_account` code. Example: `4521` ## Response **account\_id** `integer` ID of the account the webhook was registered for. Example: `4521` **events** `string[]` Events the webhook receives. Allowed values: `onboarding`, `payin`, `payout`, `kyc` Example: `["payin", "payout"]` **url** `string` Endpoint URL that was registered to receive webhook notifications. Example: `https://my-url.requestcatcher.com/test` **secret** `string` Secret used to sign the webhooks delivered to this URL, or `null` if none is set. Example: `whsec_9f8e7d6c5b4a3210` ## Request Example ```bash cURL theme={null} curl --request POST \ --url https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' \ --header 'Content-Type: application/json' \ --data '{ "events": ["payin", "payout"], "url": "https://my-url.requestcatcher.com/test", "secret": "whsec_9f8e7d6c5b4a3210", "account_id": 4521 }' ``` ```javascript JavaScript theme={null} const response = await fetch('https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks', { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ events: ['payin', 'payout'], url: 'https://my-url.requestcatcher.com/test', secret: 'whsec_9f8e7d6c5b4a3210', account_id: 4521 }) }); const data = await response.json(); console.log(data); ``` ```python Python theme={null} import requests url = 'https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' } data = { 'events': ['payin', 'payout'], 'url': 'https://my-url.requestcatcher.com/test', 'secret': 'whsec_9f8e7d6c5b4a3210', 'account_id': 4521 } response = requests.post(url, json=data, headers=headers) print(response.json()) ``` ```json 201 Created theme={null} { "account_id": 4521, "events": ["payin", "payout"], "url": "https://my-url.requestcatcher.com/test", "secret": "whsec_9f8e7d6c5b4a3210" } ``` ```json 422 Invalid account theme={null} { "error_code": "validation", "error_description": "Validation error", "fields": { "account_id": ["The account does not exist or is not linked to your merchant."] }, "field_errors": [ { "field": "account_id", "code": "invalid_account", "params": [], "message": "The account does not exist or is not linked to your merchant." } ] } ``` ```json 422 Event already registered theme={null} { "error_code": "validation", "error_description": "Validation error", "fields": { "events.1": ["A webhook for this event already exists for this account."] }, "field_errors": [ { "field": "events.1", "code": "webhook_already_exists", "params": [], "message": "A webhook for this event already exists for this account." } ] } ``` ```json 422 URL already registered theme={null} { "error_code": "validation", "error_description": "Validation error", "fields": { "url": ["A webhook with this URL already exists for this account."] }, "field_errors": [ { "field": "url", "code": "webhook_url_already_exists", "params": [], "message": "A webhook with this URL already exists for this account." } ] } ``` ```json 401 Unauthorized theme={null} { "success": false, "error": { "code": "unauthorized", "message": "Invalid API key provided" } } ``` ## Webhook Payload When an onboarding event occurs, a POST request will be sent to your webhook URL: ```json theme={null} { "id": "1234-5678-90ab-cdef-1234567890ab", "status": "active", "updated_at": "2024-01-15T10:30:00Z", "account_id": 123 } ``` > [!NOTE] > > The account\_id is only returned the first time in the webhook when the status is active. > [!NOTE] > > When the new [Onboarding Documents Flow](/api-reference/account/webhook/onboarding-documents) is enabled for a merchant, the payload for the `pending_documents` status also includes a `documents` array with the documents the client must send. > [!NOTE] > > Your webhook endpoint must return a `200 OK` status code to acknowledge receipt. If the endpoint fails or returns an error, delivery is retried **up to 3 times, every 15 minutes**. # Update Source: https://docs.wepayout.co/api-reference/account/webhook/webhook-update PUT /v2/register/companies/webhooks Update the URL, events and secret of an existing webhook # Update Webhook This endpoint allows updating the URL, the events and the signing secret of a registered webhook. * The webhook is identified by its `url` and the optional `account_id`, both sent in the request body. The path never carries the URL * To move the webhook to another address, send the new address in `new_url` * `events` replaces the whole list: to stop receiving an event on this URL, send the list without it; to start receiving one, add it > [!WARNING] > > Registering, updating or removing a webhook may take up to **5 minutes** to take effect. Until then, webhooks keep being delivered to the previous destination. ## Request Body **url** `string` *required* Current URL of the webhook that will be updated. Together with `account_id`, it identifies the webhook. If the account has no webhook with this URL, the request fails with `404`. Maximum length: 120 characters Example: `https://my-url.requestcatcher.com/test` **new\_url** `string` New endpoint URL for the webhook. When omitted, the URL stays the same. It must not be registered on another webhook of the account (URLs that differ only in letter case count as the same URL); otherwise the request fails with `422` and the `webhook_url_already_exists` code. Maximum length: 120 characters Example: `https://my-url.requestcatcher.com/new` **events** `string[]` *required* Complete list of events the webhook will receive after the update. Send at least one event, without repeating any. Allowed values: `onboarding`, `payin`, `payout`, `kyc` Each event can be on only one webhook per account: sending an event that another webhook of the account already receives fails with `422` and the `webhook_already_exists` code on that item (for example `events.0`). Remove it from the other webhook first. Example: `["payin", "payout"]` **secret** `string` Secret used to sign the `payin`, `payout` and `kyc` webhooks with [HMAC-SHA256](/concepts/webhooks#hmac-sha256-signature). When provided, every webhook delivered to this URL includes the `x-webhook-wp-signature` header. Maximum length: 255 characters. Use a long, randomly generated value. Example: `whsec_9f8e7d6c5b4a3210` **account\_id** `integer` ID of the account whose webhook will be updated: your own merchant or one of its subaccounts. When omitted, the webhook of **your merchant** (the authenticated account) is updated. If the account does not exist or is not linked to your merchant, the request fails with `422` and the `invalid_account` code. Example: `4521` > [!WARNING] > > Without `account_id`, the update always targets **your merchant**, even if the webhook you want to change was listed by [Query](/api-reference/account/webhook/webhook-query) under a subaccount. Send the `account_id` returned with the webhook to update the right one. > [!WARNING] > > The update replaces the whole configuration. If `secret` is omitted or `null`, the current secret is **removed** and the webhooks are no longer signed. Always send the secret you want to keep. > [!WARNING] > > An event left out of `events` stops being delivered to this URL. On a subaccount, it then goes to the main account's webhook for that event, if there is one — see [Subaccounts without a webhook](/api-reference/account/webhook/webhook-setup#subaccounts-without-a-webhook). > [!TIP] > > To rotate the secret, send the new value in `secret`. Changes may take up to **5 minutes** to take effect, so accept signatures computed with either the old or the new secret during this period. ## Response **account\_id** `integer` ID of the account the webhook belongs to. Example: `4521` **events** `string[]` Events the webhook receives after the update. Allowed values: `onboarding`, `payin`, `payout`, `kyc` Example: `["payin", "payout"]` **url** `string` Endpoint URL of the webhook after the update Example: `https://my-url.requestcatcher.com/new` **secret** `string` Secret used to sign the webhooks delivered to this URL, or `null` if none is set. Example: `whsec_9f8e7d6c5b4a3210` ## Request Example ```bash cURL theme={null} curl --request PUT \ --url https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://my-url.requestcatcher.com/test", "new_url": "https://my-url.requestcatcher.com/new", "events": ["payin", "payout"], "secret": "whsec_9f8e7d6c5b4a3210", "account_id": 4521 }' ``` ```javascript JavaScript theme={null} const response = await fetch('https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks', { method: 'PUT', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' }, body: JSON.stringify({ url: 'https://my-url.requestcatcher.com/test', new_url: 'https://my-url.requestcatcher.com/new', events: ['payin', 'payout'], secret: 'whsec_9f8e7d6c5b4a3210', account_id: 4521 }) }); const data = await response.json(); console.log(data); ``` ```python Python theme={null} import requests url = 'https://api.sandbox.wepayout.com.br/v2/register/companies/webhooks' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' } data = { 'url': 'https://my-url.requestcatcher.com/test', 'new_url': 'https://my-url.requestcatcher.com/new', 'events': ['payin', 'payout'], 'secret': 'whsec_9f8e7d6c5b4a3210', 'account_id': 4521 } response = requests.put(url, json=data, headers=headers) print(response.json()) ``` ```json 200 OK theme={null} { "account_id": 4521, "events": ["payin", "payout"], "url": "https://my-url.requestcatcher.com/new", "secret": "whsec_9f8e7d6c5b4a3210" } ``` ```json 404 Not Found theme={null} { "message": "Webhook not found." } ``` ```json 422 Invalid account theme={null} { "error_code": "validation", "error_description": "Validation error", "fields": { "account_id": ["The account does not exist or is not linked to your merchant."] }, "field_errors": [ { "field": "account_id", "code": "invalid_account", "params": [], "message": "The account does not exist or is not linked to your merchant." } ] } ``` ```json 422 Event on another webhook theme={null} { "error_code": "validation", "error_description": "Validation error", "fields": { "events.0": ["A webhook for this event already exists for this account."] }, "field_errors": [ { "field": "events.0", "code": "webhook_already_exists", "params": [], "message": "A webhook for this event already exists for this account." } ] } ``` ```json 422 New URL already registered theme={null} { "error_code": "validation", "error_description": "Validation error", "fields": { "new_url": ["A webhook with this URL already exists for this account."] }, "field_errors": [ { "field": "new_url", "code": "webhook_url_already_exists", "params": [], "message": "A webhook with this URL already exists for this account." } ] } ``` # Cancel Authorization Source: https://docs.wepayout.co/api-reference/automatic-pix/authorizations/cancel DELETE /v2/automatic-pix/authorizations/{id} Cancel an authorization ## Path Parameters **id** `integer` *required* The ID of the authorization to cancel. ## Response **id** `integer` Authorization ID **merchant\_id** `integer` Merchant ID **contract\_id** `string` Contract ID **identifier** `string` Identifier **frequency** `string` Frequency **contract\_name** `string` Contract Name **type** `string` Type **authorization\_amount** `number or null` Authorization Amount **amount** `number or null` Amount **maximum\_authorization\_amount** `number or null` Maximum Authorization Amount **start\_date** `string` Start Date **end\_date** `string or null` End Date **created\_at** `string` Creation Date **status** `object` Status **status properties** **id** `integer` Status ID **name** `string` Status Name **history** `array or null` History **history items** **id** `integer` History ID **authorization\_id** `integer` Authorization ID **status\_id** `integer` Status ID **status\_name** `string` Status Name **created\_at** `string` Date **buyer** `object` Buyer **buyer properties** **id** `integer` Buyer ID **name** `string` Buyer Name **document** `string` Buyer Document ```json 200 theme={null} { "id": 1, "merchant_id": 1, "contract_id": "123", "identifier": "identifier", "frequency": "MONTHLY", "contract_name": "Contract Name", "type": "RECURRING", "authorization_amount": 100.00, "amount": 100.00, "maximum_authorization_amount": 200.00, "start_date": "2023-01-01", "end_date": "2023-12-31", "created_at": "2023-01-01T00:00:00Z", "status": { "id": 2, "name": "CANCELED" }, "history": [ { "id": 1, "authorization_id": 1, "status_id": 1, "status_name": "ACTIVE", "created_at": "2023-01-01T00:00:00Z" }, { "id": 2, "authorization_id": 1, "status_id": 2, "status_name": "CANCELED", "created_at": "2023-01-02T00:00:00Z" } ], "buyer": { "id": 1, "name": "Buyer Name", "document": "12345678900" } } ``` # Create Authorization Source: https://docs.wepayout.co/api-reference/automatic-pix/authorizations/create POST /v2/payin/payments Create an Automatic Pix authorization # Create Authorization Create an Automatic Pix authorization using the payin creation endpoint. ## Request Body **merchant\_id** `integer` Merchant id of the account that is creating the payin. Mandatory if there is more than one account under your umbrella (sellers). **invoice** `string` *required* Your identification number, it must be unique on our database. **notification\_url** `string` The url where we will submit the callbacks. **payment\_method** `string` *required* Payment method that will be used in payin. Allowed value: `pix` **amount** `integer` *required* The charge total amount in the smallest currency unit. Min: `1` **currency** `string` *required* Currency code of the amount (ISO 4217). Example: `BRL` **country** `string` *required* Country code (ISO 3166-1 alpha-2). Example: `BR` **buyer** `object` *required* The person you are charging object. **pix** `object` *required* Pix QRCode specific instructions. **Pix Object** **expire\_date** `string` *required* The charge expiration date. Format: `YYYY-MM-DDTHH:MM:SS` **automatic\_pix** `object` *required* Automatic Pix configuration object. **Automatic Pix Object** **frequency** `string` *required* Recurrence frequency. Allowed values: `weekly`, `monthly`, `quarterly`, `semiannual`, `annual` **amount** `integer` The fixed amount to be charged in each cycle. Required if `minimum_authorization_amount` is not provided. **minimum\_authorization\_amount** `integer` The minimum amount for authorization. Required if `amount` is not provided. **authorization\_amount** `integer` The amount to be authorized. Required when `minimum_authorization_amount` is provided. **type** `string` *required* The type of the automatic pix. Allowed values: `immediate`, `optional` **contract\_id** `string` *required* Unique identifier for the contract (invoice ID). **contract\_name** `string` *required* Name of the contract (invoice name). **authorization\_notification\_url** `string` URL to receive authorization notifications. **start\_date** `string` *required* The start date of the automatic pix. Format: `YYYY-MM-DD` **number\_of\_cycles** `integer` Number of cycles for the automatic pix. ## Request Example ```bash Automatic Pix theme={null} curl --location 'https://api.sandbox.wepayout.co/v2/payin/payments' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_TOKEN_HERE' \ --data-raw '{ "payment_method": "pix", "invoice": "INV-AUTOPIX-2026-0001", "currency": "BRL", "amount": 3000, "country": "BR", "buyer": { "name": "Lucas Almeida", "email": "lucas.almeida@example.com", "document": { "type": "CPF", "number": "12345678909" } }, "pix": { "expire_date": "2026-12-31T23:59:59" }, "automatic_pix": { "frequency": "monthly", "amount": 3000, "type": "immediate", "contract_id": "CONTRACT-1234", "contract_name": "Monthly Service", "start_date": "2026-05-01" } }' ``` ## Response Example ```json 201 theme={null} { "id": 54822, "merchant": { "id": 512, "name": "Acme Sandbox Store" }, "hash": "a7d6c5f4e3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2f8b4d3c2e1a9", "payment_page": "https://pagar.sandbox.goboleto.com/?hash=a7d6c5f4e3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2f8b4d3c2e1a9", "our_number": "33046", "notification_url": null, "payment_method": "pix", "amount": 3000, "invoice": "INV-AUTOPIX-2026-0001", "paid_amount": null, "refunded_amount": null, "currency": { "id": 19, "name": "Reais", "code": "BRL", "symbol": "R$" }, "description": "", "created_at": "2026-04-30T12:15:10.000000Z", "updated_at": "2026-04-30T12:15:13.000000Z", "buyer": { "name": "Lucas Almeida", "email": "lucas.almeida@example.com", "document": { "type": "cpf", "number": "12345678909" }, "address": { "country": "BR", "city": null, "street": null, "number": null, "complement": null, "zipcode": null, "district": null, "state_code": null } }, "originator_legal_entity": { "name": null, "document": null, "helpdesk": null }, "splits": [], "pix": { "expire_date": "2025-12-31T23:59:59", "refund_mode": "FULL_REFUND_MERCHANT", "qr_code": "00020126910014BR.GOV.BCB.PIX2569api-pix-h.bancobs2.com.br/spi/v2/11111111-2222-3333-4444-555555555555520400005303986540530.005802BR5908Wepayout6014Belo Horizonte61083038040362070503***63041234", "end_to_end": null, "fine": { "percent": null, "amount": null, "date": null }, "discount": { "percent": null, "amount": null, "date": null } }, "automatic_pix": { "authorization_id": "auth_123456", "schedule_id": "sch_123456", "contract_id": "CONTRACT-1234" }, "status": { "id": 1, "name": "Created" }, "status_history": [ { "status": { "id": 1, "name": "Created" }, "updated_at": "2026-04-30T12:15:13.000000Z" } ], "substatus": null, "refunds": [] } ``` # Get Authorization Source: https://docs.wepayout.co/api-reference/automatic-pix/authorizations/get GET /v2/automatic-pix/authorizations/{id} Get an authorization by ID ## Path Parameters **id** `integer` *required* The ID of the authorization to retrieve. ## Response **id** `integer` Authorization ID **merchant\_id** `integer` Merchant ID **contract\_id** `string` Contract ID **identifier** `string` Identifier **frequency** `string` Frequency **contract\_name** `string` Contract Name **type** `string` Type **authorization\_amount** `number or null` Authorization Amount **amount** `number or null` Amount **maximum\_authorization\_amount** `number or null` Maximum Authorization Amount **start\_date** `string` Start Date **end\_date** `string or null` End Date **created\_at** `string` Creation Date **status** `object` Status **status properties** **id** `integer` Status ID **name** `string` Status Name **history** `array or null` History **history items** **id** `integer` History ID **authorization\_id** `integer` Authorization ID **status\_id** `integer` Status ID **status\_name** `string` Status Name **created\_at** `string` Date **buyer** `object` Buyer **buyer properties** **id** `integer` Buyer ID **name** `string` Buyer Name **document** `string` Buyer Document ```json 200 theme={null} { "id": 1, "merchant_id": 1, "contract_id": "123", "identifier": "identifier", "frequency": "MONTHLY", "contract_name": "Contract Name", "type": "RECURRING", "authorization_amount": 100.00, "amount": 100.00, "maximum_authorization_amount": 200.00, "start_date": "2023-01-01", "end_date": "2023-12-31", "created_at": "2023-01-01T00:00:00Z", "status": { "id": 1, "name": "ACTIVE" }, "history": [ { "id": 1, "authorization_id": 1, "status_id": 1, "status_name": "ACTIVE", "created_at": "2023-01-01T00:00:00Z" } ], "buyer": { "id": 1, "name": "Buyer Name", "document": "12345678900" } } ``` # List Authorizations Source: https://docs.wepayout.co/api-reference/automatic-pix/authorizations/list GET /v2/automatic-pix/authorizations List all authorizations ## Response **Response** `array` List of authorizations **authorization object** **id** `integer` Authorization ID **merchant\_id** `integer` Merchant ID **contract\_id** `string` Contract ID **identifier** `string` Identifier **frequency** `string` Frequency **contract\_name** `string` Contract Name **type** `string` Type **authorization\_amount** `number or null` Authorization Amount **amount** `number or null` Amount **maximum\_authorization\_amount** `number or null` Maximum Authorization Amount **start\_date** `string` Start Date **end\_date** `string or null` End Date **created\_at** `string` Creation Date **status** `object` Status **status properties** **id** `integer` Status ID **name** `string` Status Name **history** `array or null` History **history items** **id** `integer` History ID **authorization\_id** `integer` Authorization ID **status\_id** `integer` Status ID **status\_name** `string` Status Name **created\_at** `string` Date **buyer** `object` Buyer **buyer properties** **id** `integer` Buyer ID **name** `string` Buyer Name **document** `string` Buyer Document ```json 200 theme={null} [ { "id": 1, "merchant_id": 1, "contract_id": "123", "identifier": "identifier", "frequency": "MONTHLY", "contract_name": "Contract Name", "type": "RECURRING", "authorization_amount": 100.00, "amount": 100.00, "maximum_authorization_amount": 200.00, "start_date": "2023-01-01", "end_date": "2023-12-31", "created_at": "2023-01-01T00:00:00Z", "status": { "id": 1, "name": "ACTIVE" }, "history": [ { "id": 1, "authorization_id": 1, "status_id": 1, "status_name": "ACTIVE", "created_at": "2023-01-01T00:00:00Z" } ], "buyer": { "id": 1, "name": "Buyer Name", "document": "12345678900" } } ] ``` # Update Authorization Source: https://docs.wepayout.co/api-reference/automatic-pix/authorizations/update PATCH /v2/automatic-pix/authorizations/{id} Update an authorization amount > [!NOTE] > > Updating an authorization only changes the **amount** — the maximum charge limit for future scheduled payments. All other fields (frequency, start date, end date, payer) are immutable once the authorization is created. If you need to change any of those, you must [cancel the authorization](/api-reference/automatic-pix/authorizations/cancel) and create a new one. > > Existing pending schedules are not affected by an authorization amount update. To apply the new amount to an upcoming payment, [cancel the schedule](/api-reference/automatic-pix/schedules/cancel) and let the system generate a new one on the next cycle. ## Path Parameters **id** `integer` *required* The ID of the authorization to update. ## Request Body **amount** `number` *required* The new amount for the authorization. Must be greater than 0. ## Response **id** `integer` Authorization ID **merchant\_id** `integer` Merchant ID **contract\_id** `string` Contract ID **identifier** `string` Identifier **frequency** `string` Frequency **contract\_name** `string` Contract Name **type** `string` Type **authorization\_amount** `number or null` Authorization Amount **amount** `number or null` Amount **maximum\_authorization\_amount** `number or null` Maximum Authorization Amount **start\_date** `string` Start Date **end\_date** `string or null` End Date **created\_at** `string` Creation Date **status** `object` Status **status properties** **id** `integer` Status ID **name** `string` Status Name **history** `array or null` History **history items** **id** `integer` History ID **authorization\_id** `integer` Authorization ID **status\_id** `integer` Status ID **status\_name** `string` Status Name **created\_at** `string` Date **buyer** `object` Buyer **buyer properties** **id** `integer` Buyer ID **name** `string` Buyer Name **document** `string` Buyer Document ```json 200 theme={null} { "id": 1, "merchant_id": 1, "contract_id": "123", "identifier": "identifier", "frequency": "MONTHLY", "contract_name": "Contract Name", "type": "RECURRING", "authorization_amount": 100.00, "amount": 150.00, "maximum_authorization_amount": 200.00, "start_date": "2023-01-01", "end_date": "2023-12-31", "created_at": "2023-01-01T00:00:00Z", "status": { "id": 1, "name": "ACTIVE" }, "history": [ { "id": 1, "authorization_id": 1, "status_id": 1, "status_name": "ACTIVE", "created_at": "2023-01-01T00:00:00Z" } ], "buyer": { "id": 1, "name": "Buyer Name", "document": "12345678900" } } ``` # Cancel Schedule Source: https://docs.wepayout.co/api-reference/automatic-pix/schedules/cancel DELETE /v2/automatic-pix/schedules/{id} Cancel a schedule ## Path Parameters **id** `integer` *required* The ID of the schedule to cancel. ## Response **id** `integer` Schedule ID **merchant\_id** `integer` Merchant ID **authorization** `object` Authorization **authorization properties** **id** `integer` Authorization ID **name** `string` Authorization Name **amount** `number` Amount **due\_date** `string` Due Date **settlement\_date** `string or null` Settlement Date **status** `object` Status **status properties** **id** `integer` Status ID **name** `string` Status Name **history** `array or null` History **history items** **id** `integer` History ID **schedule\_id** `integer` Schedule ID **status\_id** `integer` Status ID **status\_name** `string` Status Name **created\_at** `string` Date **tx\_id** `string or null` Transaction ID **attempts** `array` Attempts **attempt items** **id** `integer` Attempt ID **status** `string` Status **end\_to\_end\_id** `string` End To End ID **attempt\_date** `string` Date **created\_at** `string` Creation Date **buyer** `object` Buyer **buyer properties** **id** `integer` Buyer ID **name** `string` Buyer Name **document** `string` Buyer Document ```json 200 theme={null} { "id": 1, "merchant_id": 1, "authorization": { "id": 1, "name": "Authorization Name" }, "amount": 100.00, "due_date": "2023-01-01", "settlement_date": null, "status": { "id": 2, "name": "CANCELED" }, "history": [ { "id": 1, "schedule_id": 1, "status_id": 1, "status_name": "PENDING", "created_at": "2023-01-01T00:00:00Z" }, { "id": 2, "schedule_id": 1, "status_id": 2, "status_name": "CANCELED", "created_at": "2023-01-02T00:00:00Z" } ], "tx_id": null, "attempts": [], "created_at": "2023-01-01T00:00:00Z", "buyer": { "id": 1, "name": "Buyer Name", "document": "12345678900" } } ``` # Get Schedule Source: https://docs.wepayout.co/api-reference/automatic-pix/schedules/get GET /v2/automatic-pix/schedules/{id} Get a schedule by ID ## Path Parameters **id** `integer` *required* The ID of the schedule to retrieve. ## Response **id** `integer` Schedule ID **merchant\_id** `integer` Merchant ID **authorization** `object` Authorization **authorization properties** **id** `integer` Authorization ID **name** `string` Authorization Name **amount** `number` Amount **due\_date** `string` Due Date **settlement\_date** `string or null` Settlement Date **status** `object` Status **status properties** **id** `integer` Status ID **name** `string` Status Name **history** `array or null` History **history items** **id** `integer` History ID **schedule\_id** `integer` Schedule ID **status\_id** `integer` Status ID **status\_name** `string` Status Name **created\_at** `string` Date **tx\_id** `string or null` Transaction ID **attempts** `array` Attempts **attempt items** **id** `integer` Attempt ID **status** `string` Status **end\_to\_end\_id** `string` End To End ID **attempt\_date** `string` Date **created\_at** `string` Creation Date **buyer** `object` Buyer **buyer properties** **id** `integer` Buyer ID **name** `string` Buyer Name **document** `string` Buyer Document ```json 200 theme={null} { "id": 1, "merchant_id": 1, "authorization": { "id": 1, "name": "Authorization Name" }, "amount": 100.00, "due_date": "2023-01-01", "settlement_date": null, "status": { "id": 1, "name": "PENDING" }, "history": [ { "id": 1, "schedule_id": 1, "status_id": 1, "status_name": "PENDING", "created_at": "2023-01-01T00:00:00Z" } ], "tx_id": null, "attempts": [], "created_at": "2023-01-01T00:00:00Z", "buyer": { "id": 1, "name": "Buyer Name", "document": "12345678900" } } ``` # List Schedules Source: https://docs.wepayout.co/api-reference/automatic-pix/schedules/list GET /v2/automatic-pix/schedules List all schedules > [!NOTE] > > Schedules are created **one at a time**. When an authorization is confirmed, only the first upcoming schedule is generated. The next one is created automatically once the current schedule is paid or processed — not all future installments are pre-created upfront. > > This means that at any given time, you will typically see **one active schedule per authorization**. Additional schedules will appear in this list as their payment dates approach. ## Response **Response** `array` List of schedules **schedule object** **id** `integer` Unique identifier for this specific schedule. Each billing cycle generates a new schedule with its own ID — do not assume this ID is stable across cycles. **merchant\_id** `integer` Merchant ID **authorization** `object` Authorization **authorization properties** **id** `integer` Authorization ID **name** `string` Authorization Name **amount** `number` Amount **due\_date** `string` Due Date **settlement\_date** `string or null` Settlement Date **status** `object` Status **status properties** **id** `integer` Status ID **name** `string` Status Name **history** `array or null` History **history items** **id** `integer` History ID **schedule\_id** `integer` ID of the schedule this history entry belongs to. Matches the parent schedule `id` — each billing cycle has its own unique schedule ID. **status\_id** `integer` Status ID **status\_name** `string` Status Name **created\_at** `string` Date **tx\_id** `string or null` Transaction ID **attempts** `array` Attempts **attempt items** **id** `integer` Attempt ID **status** `string` Status **end\_to\_end\_id** `string` End To End ID **attempt\_date** `string` Date **created\_at** `string` Creation Date **buyer** `object` Buyer **buyer properties** **id** `integer` Buyer ID **name** `string` Buyer Name **document** `string` Buyer Document ```json 200 theme={null} [ { "id": 1, "merchant_id": 1, "authorization": { "id": 1, "name": "Authorization Name" }, "amount": 100.00, "due_date": "2023-01-01", "settlement_date": null, "status": { "id": 1, "name": "PENDING" }, "history": [ { "id": 1, "schedule_id": 1, "status_id": 1, "status_name": "PENDING", "created_at": "2023-01-01T00:00:00Z" } ], "tx_id": null, "attempts": [], "created_at": "2023-01-01T00:00:00Z", "buyer": { "id": 1, "name": "Buyer Name", "document": "12345678900" } } ] ``` # Update Schedule Source: https://docs.wepayout.co/api-reference/automatic-pix/schedules/update PATCH /v2/automatic-pix/schedules/{id} Update a schedule amount > [!WARNING] > > Each schedule is tied to a specific authorization. The only field that can be updated on an existing schedule is **amount**. If you need to change any other detail — such as the due date or the payer — you must [cancel the schedule](/api-reference/automatic-pix/schedules/cancel) and generate a new one. > [!NOTE] > > This update applies **only to the current schedule**. The next billing cycle will be created with the authorization's `minimum_authorization_amount` as the default, regardless of the amount set here. To change the default for all future cycles, use the [Update Authorization](/api-reference/automatic-pix/authorizations/update) endpoint. > > The schedule can only be updated while its status is **Pending**. Once it moves to Sent or beyond, no further changes are possible. ## Path Parameters **id** `integer` *required* The ID of the schedule to update. ## Request Body **amount** `number` *required* The new amount for the schedule. Must be greater than 0. ## Response **id** `integer` Schedule ID **merchant\_id** `integer` Merchant ID **authorization** `object` Authorization **authorization properties** **id** `integer` Authorization ID **name** `string` Authorization Name **amount** `number` Amount **due\_date** `string` Due Date **settlement\_date** `string or null` Settlement Date **status** `object` Status **status properties** **id** `integer` Status ID **name** `string` Status Name **history** `array or null` History **history items** **id** `integer` History ID **schedule\_id** `integer` Schedule ID **status\_id** `integer` Status ID **status\_name** `string` Status Name **created\_at** `string` Date **tx\_id** `string or null` Transaction ID **attempts** `array` Attempts **attempt items** **id** `integer` Attempt ID **status** `string` Status **end\_to\_end\_id** `string` End To End ID **attempt\_date** `string` Date **created\_at** `string` Creation Date **buyer** `object` Buyer **buyer properties** **id** `integer` Buyer ID **name** `string` Buyer Name **document** `string` Buyer Document ```json 200 theme={null} { "id": 1, "merchant_id": 1, "authorization": { "id": 1, "name": "Authorization Name" }, "amount": 150.00, "due_date": "2023-01-01", "settlement_date": null, "status": { "id": 1, "name": "PENDING" }, "history": [ { "id": 1, "schedule_id": 1, "status_id": 1, "status_name": "PENDING", "created_at": "2023-01-01T00:00:00Z" } ], "tx_id": null, "attempts": [], "created_at": "2023-01-01T00:00:00Z", "buyer": { "id": 1, "name": "Buyer Name", "document": "12345678900" } } ``` # List Authorization History Webhooks Source: https://docs.wepayout.co/api-reference/automatic-pix/webhooks/list-authorization-history GET /v2/automatic-pix/webhooks/authorization-history/{id} List webhooks for an authorization history ## Path Parameters **id** `integer` *required* The ID of the authorization history. ## Response **webhooks** `array` List of webhooks **webhook object** **id** `string` Webhook ID **url** `string` Webhook URL **status** `integer` HTTP Status Code **request\_body** `string` Request Body **response\_body** `string` Response Body **created\_at** `string` Creation Date ```json 200 theme={null} [ { "id": "webhook-id", "url": "https://callback.url", "status": 200, "request_body": "{\"id\": 1, \"status\": \"ACTIVE\"}", "response_body": "OK", "created_at": "2023-01-01T00:00:00Z" } ] ``` # List Schedule Webhooks Source: https://docs.wepayout.co/api-reference/automatic-pix/webhooks/list-schedule GET /v2/automatic-pix/webhooks/schedule/{id} List webhooks for a schedule ## Path Parameters **id** `integer` *required* The ID of the schedule. ## Response **webhooks** `array` List of webhooks **webhook object** **id** `string` Webhook ID **url** `string` Webhook URL **status** `integer` HTTP Status Code **request\_body** `string` Request Body **response\_body** `string` Response Body **created\_at** `string` Creation Date ```json 200 theme={null} [ { "id": "webhook-id", "url": "https://callback.url", "status": 200, "request_body": "{\"id\": 1, \"status\": \"PENDING\"}", "response_body": "OK", "created_at": "2023-01-01T00:00:00Z" } ] ``` # Resend Authorization Webhook Source: https://docs.wepayout.co/api-reference/automatic-pix/webhooks/resend-authorization-history POST /v2/automatic-pix/webhooks/authorization-history/{id}/resend Resend a webhook for an authorization history ## Path Parameters **id** `integer` *required* The ID of the authorization history. ## Response **message** `string` Success message ```json 200 theme={null} { "message": "webhook resent successfully" } ``` # Resend Schedule Webhook Source: https://docs.wepayout.co/api-reference/automatic-pix/webhooks/resend-schedule POST /v2/automatic-pix/webhooks/schedule/resend/{historyId} Resend a webhook for a schedule history ## Path Parameters **historyId** `integer` *required* The ID of the schedule history. ## Response **message** `string` Success message ```json 200 theme={null} { "message": "webhook resent successfully" } ``` # List Institutions Source: https://docs.wepayout.co/api-reference/banks/list-institutions GET /v2/banks Return the list of banks available in Brazil # List Institutions Return the list of banks available in Brazil. ## Query Parameters **created\_after** `string` created after **created\_before** `string` created before **id** `string` ISPB bank **ispb\_authorized** `boolean` To clear whether this bank is authorized ISPB **name** `string` name of bank **order\_by** `string` Define the ordering of the query. Allowed values: `bank_id`, `code`, `name`, `document_name`, `logo`, `created_at`, `updated_at`. Default: `id` **page** `integer` The current page that will be displayed on returned list. **per\_page** `integer` The number of banks that will be displayed per page on paginated lists. **sort** `string` Define the sort order: ascending or descending **updated\_after** `string` updated after **updated\_before** `string` updated before ## Response **id** `number` internal id **code** `string` bank code **ispb** `string` ISPB code **name** `string` Date name **logo** `string` logo **created\_at** `string` Create date **updated\_at** `string` Update date **deleted\_at** `string` Delete date **ispb\_authorized** `boolean` Informs whether the ISPB of that institution is authorized or not ```json 200 OK theme={null} [ { "id": 1270, "code": "237", "ispb": "00000000", "name": "BANCO DO BRASIL S.A. - INSTITUIÇÃO DE PAGAMEN", "logo": null, "created_at": "2024-06-25 00:00:00.00", "updated_at": "2024-06-25 00:00:00.00", "deleted_at": null, "ispb_authorized": false } ] ``` ## Use Cases ### Display Bank List in UI ```javascript theme={null} async function loadBankOptions() { const response = await fetch('https://api.wepayments.com/v1/banks/institutions', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }); const { data } = await response.json(); const select = document.getElementById('bank-select'); data.forEach(bank => { const option = document.createElement('option'); option.value = bank.code; option.textContent = bank.name; select.appendChild(option); }); } ``` ### Validate Bank Code ```javascript theme={null} async function validateBankCode(code) { const response = await fetch('https://api.wepayments.com/v1/banks/institutions', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }); const { data } = await response.json(); return data.some(bank => bank.code === code); } ``` ### Search Banks ```javascript theme={null} async function searchBanks(query) { const response = await fetch('https://api.wepayments.com/v1/banks/institutions', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }); const { data } = await response.json(); const lowerQuery = query.toLowerCase(); return data.filter(bank => bank.name.toLowerCase().includes(lowerQuery) || bank.short_name.toLowerCase().includes(lowerQuery) ); } ``` ## Best Practices > [accordion] Cache the Response > > The list of institutions doesn't change frequently. Cache the response to reduce API calls: > > ```javascript theme={null} > const CACHE_KEY = 'banks_list'; > const CACHE_DURATION = 7 * 24 * 60 * 60 * 1000; // 7 days > > async function getBanks() { > const cached = localStorage.getItem(CACHE_KEY); > const timestamp = localStorage.getItem(`${CACHE_KEY}_time`); > > if (cached && timestamp) { > const age = Date.now() - parseInt(timestamp); > if (age < CACHE_DURATION) { > return JSON.parse(cached); > } > } > > const response = await fetch('https://api.wepayments.com/v1/banks/institutions', { > headers: { 'Authorization': 'Bearer YOUR_API_KEY' } > }); > > const data = await response.json(); > localStorage.setItem(CACHE_KEY, JSON.stringify(data)); > localStorage.setItem(`${CACHE_KEY}_time`, Date.now().toString()); > > return data; > } > ``` > [accordion] Handle Errors Gracefully > > Always handle potential errors when fetching the bank list: > > ```javascript theme={null} > try { > const banks = await fetchBanks(); > displayBanks(banks); > } catch (error) { > console.error('Failed to load banks:', error); > showErrorMessage('Unable to load bank list. Please try again later.'); > } > ``` > [accordion] Filter by Type > > If you only need specific types of institutions, filter the results: > > ```javascript theme={null} > const banks = await fetchBanks(); > const traditionalBanks = banks.data.filter(bank => bank.type === 'bank'); > ``` ## Rate Limiting This endpoint is subject to rate limiting. Please cache the response and avoid making excessive requests. # Cancel Charges by Period Source: https://docs.wepayout.co/api-reference/cash-in/payin/cancel-by-period DELETE /v2/payin/payments/request-cancel-by-period Request the cancellation of a merchant Payins created within a period # Cancel Charges by Period Request the asynchronous cancellation of every eligible Payin created by a merchant within a date range, filtered by payment method. Useful when a merchant needs all of its open charges canceled at once (e.g. when the account is being deactivated). > [!NOTE] > > This is an **asynchronous** request. The response returns the **estimated** number of charges > that matched the filters and were queued for cancellation. The actual cancellation is performed > by background jobs. ## Eligibility > [!WARNING] > > **Cancellation Restrictions** — a charge is only queued for cancellation when it: > > * has `status = created` > * was created between `start_date` and `end_date` > * matches one of the requested `payment_method` values > * respects the minimum time since creation (see below) ## Minimum Time Before Cancellation * **pix**: at least 5 minutes after creation * **billet**: at least 30 minutes after creation ## Request Body **merchant\_id** `integer` *required* The ID of the merchant whose charges will be canceled. Must belong to the authenticated user. **start\_date** `string` *required* Start of the creation period, format `Y-m-d H:i:s`. Example: `2025-09-30 00:00:00` **end\_date** `string` *required* End of the creation period, format `Y-m-d H:i:s`. Must be after `start_date`. Example: `2025-12-31 00:00:00` **payment\_method** `array` *required* The payment methods to include in the cancellation. Must contain at least one value. Useful values: * `pix` * `billet` > [!WARNING] > > The value `credit-card` is accepted by validation but credit-card charges are **never** > eligible for cancellation, so including it has no effect. ## Response **status** `boolean` Indicates if the cancellation request was successfully accepted. **data** `object` Response data object. **Data** **estimated\_total** `integer` The estimated number of charges that matched the filters and were queued for cancellation. **message** `string` Confirmation message about the cancellation request. ## Request Example ```bash cURL theme={null} curl --request DELETE \ --url https://api.sandbox.wepayout.com.br/v2/payin/payments/request-cancel-by-period \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' \ --header 'Content-Type: application/json' \ --data '{ "merchant_id": 123, "start_date": "2025-09-30 00:00:00", "end_date": "2025-12-31 00:00:00", "payment_method": ["pix", "billet"] }' ``` ```javascript JavaScript theme={null} async function cancelChargesByPeriod(payload) { const response = await fetch( 'https://api.sandbox.wepayout.com.br/v2/payin/payments/request-cancel-by-period', { method: 'DELETE', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer 123', 'Content-Type': 'application/json' }, body: JSON.stringify(payload) } ); return await response.json(); } // Usage const result = await cancelChargesByPeriod({ merchant_id: 123, start_date: '2025-09-30 00:00:00', end_date: '2025-12-31 00:00:00', payment_method: ['pix', 'billet'] }); console.log('Cancellation result:', result); ``` ```python Python theme={null} import requests def cancel_charges_by_period(payload): url = 'https://api.sandbox.wepayout.com.br/v2/payin/payments/request-cancel-by-period' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer 123', 'Content-Type': 'application/json' } response = requests.delete(url, headers=headers, json=payload) return response.json() # Usage result = cancel_charges_by_period({ 'merchant_id': 123, 'start_date': '2025-09-30 00:00:00', 'end_date': '2025-12-31 00:00:00', 'payment_method': ['pix', 'billet'] }) print('Cancellation result:', result) ``` ```json 200 OK theme={null} { "status": true, "data": { "estimated_total": 42 }, "message": "Cancellation requested successfully" } ``` ```json 404 Not Found theme={null} { "status": false, "message": "It is not possible to cancel payins with the applied filters." } ``` ```json 422 Unprocessable Entity theme={null} { "message": "The given data was invalid.", "errors": { "end_date": [ "The end date must be a date after start date." ] } } ``` ## Important Notes > [!NOTE] > > **Pix Cancellation**: Pix charges are canceled instantly once the job runs. > [!WARNING] > > **Billet Cancellation**: Billet charges require at least 1 day to move from `drop_requested` to `canceled`, as the process depends on confirmation from the payment processor. > [!TIP] > > To cancel a specific set of charges instead of a whole period, use [Cancel Charges](/api-reference/cash-in/payin/request-multiple-cancel) with a list of IDs. # Create Charge (Bank Slip) Source: https://docs.wepayout.co/api-reference/cash-in/payin/create-charge-bank-slip POST /v2/payin/payments Generate a new Boleto payment request # Create Charge (Bank Slip) Generate a new Boleto payment request. ## Request Body **merchant\_id** `integer` Merchant id of the account that is creating the payin. Mandatory if there is more than one account under your umbrella (sellers). **invoice** `string` *required* Your identification number, it must be unique on our database. **notification\_url** `string` The url where we will submit the callbacks. **payment\_method** `string` *required* Payment method that will be used in payin. Allowed value: `boleto` **amount** `integer` *required* The charge total amount in the smallest currency unit. Min: `500` **currency** `string` *required* Currency code of the amount (ISO 4217). Example: `BRL` **country** `string` *required* Country code (ISO 3166-1 alpha-2). Example: `BR` **description** `string` Instructions that will be displayed to the user. **buyer** `object` *required* The person you are charging object. **Buyer Object** **name** `string` *required* The buyer name. **email** `string` *required* Buyer email address. **document** `object` *required* The buyer document. **Document Object** **type** `string` *required* Document type. Example: `CPF`, `CNPJ` **number** `string` *required* Document number. **address** `object` *required* The buyer's address. **Address Object** **street** `string` *required* Street name. **number** `string` *required* Street number. **zipcode** `string` *required* ZIP/Postal code. **city** `string` *required* City name. **district** `string` *required* District/Neighborhood. **state\_code** `string` *required* State code. **originator\_legal\_entity** `object` *required* Use this object to inform the legal name of the final beneficiary. **boleto** `object` *required* Boleto specific instructions. **Boleto Object** **expire\_date** `string` *required* The payin expiration date. Format: `YYYY-MM-DD` ## Request Example ```bash Boleto theme={null} curl --location 'https://api.sandbox.wepayout.co/v2/payin/payments' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_TOKEN_HERE' \ --data-raw '{ "payment_method": "boleto", "invoice": "YOUR-INVOICE-CODE", "currency": "BRL", "amount": 500, "country": "BR", "buyer": { "name": "Buyer Name", "email": "buyer@example.com", "document": { "type": "CPF", "number": "12345678901" }, "address": { "street": "Street Name", "number": "123", "zipcode": "12345000", "city": "City Name", "district": "District Name", "state_code": "SP" } }, "originator_legal_entity": { "name": "Company Name", "document": "12345678901", "helpdesk": "company.com" }, "boleto": { "expire_date": "2025-12-31" } }' ``` ## Response **id** `integer` WEpayments auto generated id, use this id to perform conciliation or perform queries via API / Dashboard. **merchant** `object` Merchant object. **Merchant** **id** `integer` Id of the WE account that created the payin. **name** `string` Name of the WE account that created the payin. **hash** `string` WEpayments auto generated hash, use this hash to send your user to the payment page. **payment\_page** `string` The WEpayments payment page where you can redirect the end customer. **our\_number** `string` The bank identification number. **invoice** `string` Your identification number. **notification\_url** `string` The url where callbacks are submitted. **payment\_method** `string` Payment method used in payin. Value: `boleto` **amount** `integer` The payin total amount in cents. **paid\_amount** `integer` The total amount of the payin paid. **refunded\_amount** `integer` Amount refunded from this charge. **currency** `object` Currency object. **Currency** **id** `integer` Currency id. **name** `string` Currency name. **code** `string` Currency code (ISO 4217). **symbol** `string` Currency symbol. **description** `string` Instructions displayed to the user. **buyer** `object` The person you are charging object. **originator\_legal\_entity** `object` Final beneficiary object. **boleto** `object` Boleto specific instructions object. **Boleto Response** **expire\_date** `string` Expiration date in format `YYYY-MM-DD`. **digitable\_line** `string` Digitable line for boleto payment. **bar\_code\_number** `string` Barcode number for boleto. **agreement** `object` Extra data for boleto rendering. **fine** `object` Fine object. **discount** `object` Discount object. **status** `object` Status object. **Status** **id** `integer` Status id. **name** `string` Status name. **status\_history** `array` Status history object. **substatus** `object` Substatus object. Can be null. **refunds** `array` Refund object list. **created\_at** `string` Cash-in created date. **updated\_at** `string` Cash-in update date. ## Response Example ```json 201 Bank Slip theme={null} { "id": 54830, "merchant": { "id": 512, "name": "Acme Sandbox Store" }, "hash": "9c8d7e6f5a4b3c2f8b4d3c2e1a9a7d6c5f4e3a2b1c0d9e8f7a6b5c4d3e2f1a0", "payment_page": "https://pagar.sandbox.goboleto.com/?hash=9c8d7e6f5a4b3c2f8b4d3c2e1a9a7d6c5f4e3a2b1c0d9e8f7a6b5c4d3e2f1a0", "our_number": "991777551234", "invoice": "f3a9b1d4-8a11-4d99-b9cd-1234567890ab", "notification_url": null, "payment_method": "boleto", "amount": 500, "paid_amount": null, "refunded_amount": null, "currency": { "id": 19, "name": "Reais", "code": "BRL", "symbol": "R$" }, "description": "", "created_at": "2026-04-30T12:20:39.000000Z", "updated_at": "2026-04-30T12:20:39.000000Z", "buyer": { "name": "Maria Souza", "email": "maria.souza@example.com", "document": { "type": "cpf", "number": "12345678909" }, "address": { "country": "BR", "city": "Barueri", "street": "Alameda Rio Azul", "number": "500", "complement": "Bloco B Sala 1503", "zipcode": "06454000", "district": "Alphaville Industrial", "state_code": "SP" } }, "originator_legal_entity": { "name": "North Pole Commerce", "document": "10987654321", "helpdesk": "support.northpole.example" }, "splits": [], "boleto": { "expire_date": "2027-12-31", "digitable_line": "10499.63208 34000.100049 66666.344205 1 81490000000200", "bar_code_number": "10491814900000002009632034000900041179634666", "agreement": { "number": "666666", "digit": "6", "agency": "9999", "assignor_code": "9999/666666-6" }, "fine": { "percent": 2, "amount": 10, "date": "2027-12-30" }, "discount": { "percent": null, "amount": null, "daily_amount": null, "date": null } }, "status": { "id": 1, "name": "Created" }, "status_history": [ { "status": { "id": 1, "name": "Created" }, "updated_at": "2026-04-30T12:20:39.000000Z" } ], "substatus": null, "refunds": [], "automatic_pix": null } ``` ## Related Resources > [card] [Create Charge (Pix)](/api-reference/cash-in/payin/create-charge-pix) > > Use the same endpoint with pix-specific required fields > [card] [Get Unique Charge](/api-reference/cash-in/payin/get-unique-charge) > > Retrieve a specific charge by ID # Create Charge (Pix) Source: https://docs.wepayout.co/api-reference/cash-in/payin/create-charge-pix POST /v2/payin/payments Generate a new Pix payment request # Create Charge (Pix) Generate a new Pix payment request. ## Request Body **merchant\_id** `integer` Merchant id of the account that is creating the payin. Mandatory if there is more than one account under your umbrella (sellers). **invoice** `string` *required* Your identification number, it must be unique on our database. **notification\_url** `string` The url where we will submit the callbacks. **payment\_method** `string` *required* Payment method that will be used in payin. Allowed value: `pix` **amount** `integer` *required* The charge total amount in the smallest currency unit (e.g., 100 cents to charge R\$1.00). Min: `1` **currency** `string` *required* Currency code of the amount (ISO 4217). Example: `BRL` **country** `string` *required* Country code (ISO 3166-1 alpha-2). Example: `BR` **description** `string` Instructions that will be displayed to the user. **buyer** `object` *required* The person you are charging object. **Buyer Object** **name** `string` *required* The buyer name. **email** `string` *required* Buyer email address. **document** `object` *required* The buyer document. **Document Object** **type** `string` *required* Document type. Example: `CPF`, `CNPJ` **number** `string` *required* Document number. **pix** `object` *required* Pix QRCode specific instructions. **Pix Object** **expire\_date** `string` *required* The charge expiration date. Format: `YYYY-MM-DDTHH:MM:SS` **refund\_mode** `string` Defines which wallet is debited when this charge is refunded. * `FULL_REFUND_MERCHANT`: the full refund amount is debited from the wallet of the merchant that created the charge, **even if the charge has splits**. * `FULL_REFUND_RECIPIENT`: the full refund amount is debited from the wallet that received the split. If the charge has more than one wallet in `splits`, the refund is rejected. * `REFUND_BY_SPLIT`: every refund must inform which wallets are debited, using the `splits` field of [Create Refund](/api-reference/cash-in/refund/create-refund). A refund without `splits` is rejected. Allowed values: `FULL_REFUND_MERCHANT`, `FULL_REFUND_RECIPIENT`, `REFUND_BY_SPLIT` Default: `FULL_REFUND_MERCHANT` > [!WARNING] > > * The refund mode is set when the charge is created and **cannot be changed** afterwards. > * If your charges have splits and refunds should be debited from the split wallet, send this field. Without it, refunds are debited from the merchant wallet. > * The balance of the wallet being debited is checked when the refund is requested. If it does not cover the refund amount, the refund is rejected with HTTP `400` (`Insufficient balance`) and nothing is debited from the merchant wallet. ## Request Example ```bash Pix theme={null} curl --location 'https://api.sandbox.wepayout.co/v2/payin/payments' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_TOKEN_HERE' \ --data-raw '{ "payment_method": "pix", "invoice": "YOUR-CODE1234", "currency": "BRL", "amount": 3000, "country": "BR", "buyer": { "name": "Buyer Name", "email": "buyer-email@wepayments.com.br", "document": { "type": "CPF", "number": "34960826312" } }, "pix": { "expire_date": "2025-12-31T23:59:59", "refund_mode": "FULL_REFUND_MERCHANT" } }' ``` ## Response **id** `integer` WEpayments auto generated id, use this id to perform conciliation or perform queries via API / Dashboard. **merchant** `object` Merchant object. **Merchant** **id** `integer` Id of the WE account that created the payin. **name** `string` Name of the WE account that created the payin. **hash** `string` WEpayments auto generated hash, use this hash to send your user to the payment page. **payment\_page** `string` The WEpayments payment page where you can redirect the end customer. **our\_number** `string` The bank identification number. **invoice** `string` Your identification number. **notification\_url** `string` The url where callbacks are submitted. **payment\_method** `string` Payment method used in payin. Value: `pix` **amount** `integer` The payin total amount in cents. **paid\_amount** `integer` The total amount of the payin paid. **refunded\_amount** `integer` Amount refunded from this charge. **currency** `object` Currency object. **Currency** **id** `integer` Currency id. **name** `string` Currency name. **code** `string` Currency code (ISO 4217). **symbol** `string` Currency symbol. **description** `string` Instructions displayed to the user. **buyer** `object` The person you are charging object. **originator\_legal\_entity** `object` Final beneficiary object. Can be null for pix. **pix** `object` Pix QRCode specific instructions object. **Pix Response** **expire\_date** `string` Expiration date in format `YYYY-MM-DDTHH:MM:SS`. **refund\_mode** `string` Refund mode applied to the charge: `FULL_REFUND_MERCHANT`, `FULL_REFUND_RECIPIENT` or `REFUND_BY_SPLIT`. See `pix.refund_mode` in the request body. **qr\_code** `string` Pix copy and paste code used by the end customer. **end\_to\_end** `string` Unique identifier for a transaction. **fine** `object` Fine object. **discount** `object` Discount object. **status** `object` Status object. **Status** **id** `integer` Status id. **name** `string` Status name. **status\_history** `array` Status history object. **substatus** `object` Substatus object. Can be null. **refunds** `array` Refund object list. **created\_at** `string` Cash-in created date. **updated\_at** `string` Cash-in update date. ## Response Example ```json 201 Pix theme={null} { "id": 54821, "merchant": { "id": 512, "name": "Acme Sandbox Store" }, "hash": "f8b4d3c2e1a9b7d6c5f4e3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2", "payment_page": "https://pagar.sandbox.goboleto.com/?hash=f8b4d3c2e1a9b7d6c5f4e3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2", "our_number": "33045", "invoice": "INV-PIX-2026-0001", "notification_url": null, "payment_method": "pix", "amount": 3000, "paid_amount": null, "refunded_amount": null, "currency": { "id": 19, "name": "Reais", "code": "BRL", "symbol": "R$" }, "description": "", "created_at": "2026-04-30T12:10:45.000000Z", "updated_at": "2026-04-30T12:10:47.000000Z", "buyer": { "name": "Lucas Almeida", "email": "lucas.almeida@example.com", "document": { "type": "cpf", "number": "12345678909" }, "address": { "country": "BR", "city": null, "street": null, "number": null, "complement": null, "zipcode": null, "district": null, "state_code": null } }, "originator_legal_entity": { "name": null, "document": null, "helpdesk": null }, "splits": [], "pix": { "expire_date": "2025-12-31T23:59:59", "refund_mode": "FULL_REFUND_MERCHANT", "qr_code": "00020126910014BR.GOV.BCB.PIX2569api-pix-h.bancobs2.com.br/spi/v2/11111111-2222-3333-4444-555555555555520400005303986540530.005802BR5908Wepayout6014Belo Horizonte61083038040362070503***63041234", "end_to_end": null, "fine": { "percent": null, "amount": null, "date": null }, "discount": { "percent": null, "amount": null, "date": null } }, "status": { "id": 1, "name": "Created" }, "status_history": [ { "status": { "id": 1, "name": "Created" }, "updated_at": "2026-04-30T12:10:47.000000Z" } ], "substatus": null, "refunds": [], "automatic_pix": null } ``` ## Related Resources > [card] [Create Authorization](/api-reference/automatic-pix/authorizations/create) > > Create automatic pix using the same payin endpoint > [card] [Create Charge (Bank Slip)](/api-reference/cash-in/payin/create-charge-bank-slip) > > Use the same endpoint with boleto-specific required fields # Get Unique Charge Source: https://docs.wepayout.co/api-reference/cash-in/payin/get-unique-charge GET /v2/payin/payments/{id} Get details of a specific charge by ID # Get Unique Charge Get details of a specific charge by ID. ## Path Parameters **id** `integer` *required* The charge ID to retrieve. Example: `32457` ## Response Returns a single charge object with all details. **id** `integer` WEpayment's auto generated id, use this id to perform conciliation or perform queries via API / Dashboard. **merchant** `object` Merchant object. **Merchant** **id** `integer` Id of the WE account that created the payin. **name** `string` Name of the WE account that created the payin. **hash** `string` WEpayments auto generated hash, use this hash to send your user to the payment page. **payment\_page** `string` The WEpayments payment page is the place where you will redirect the end customer to pay the bill. **our\_number** `string` The bank identification number. **invoice** `string` Your identification number. **notification\_url** `string` The url where we will submit the callbacks. **payment\_method** `string` Payment method that will be used in payin. Values: `pix`, `boleto` **currency** `object` Currency object. **Currency** **id** `integer` Currency id. **name** `string` Currency name. **code** `string` Currency code (ISO 4217). **symbol** `string` Currency symbol. **amount** `integer` The payin total amount in cents. **paid\_amount** `integer` The total amount of the payin paid. **refunded\_amount** `integer` Amount refunded from this charge. Only pix payment\_method. **description** `string` Instructions that will be displayed to the user. **buyer** `object` The person you are charging object. **Buyer** **name** `string` The buyer name. **email** `string` Buyer's email. **document** `object` The buyer document object. **Document** **type** `string` Document type (CPF, CNPJ). **number** `string` Document number. **address** `object` The buyer's address object. **Address** **country** `string` Country code. **city** `string` City name. **street** `string` Street name. **number** `string` Street number. **complement** `string` Address complement. **zipcode** `string` ZIP/Postal code. **district** `string` District/Neighborhood. **state\_code** `string` State code. **originator\_legal\_entity** `object` Final Beneficiary object. **Originator Legal Entity** **name** `string` The final beneficiary name to appear in the payin. **document** `string` The tax ID to appear in the charge. **helpdesk** `string` Website, e-mail address or other customer channel to appear in the payin. **pix** `object` Pix QRCode specific instructions object (when payment\_method is pix). **Pix** **expire\_date** `string` Expiration date in format YYYY-MM-DDTHH:MM:SS. **refund\_mode** `string` Type of refund mode. **qr\_code** `string` QRCode Pix / Copy and paste that will be used by your end customer to make the payin payment. **qr\_code\_url** `string` QR Code URL. **end\_to\_end** `string` Unique identifier for a transaction. **fine** `object` Fine when the expiration date is reached. **discount** `object` Discount when a certain date is reached. **boleto** `object` Boleto specific instructions object (when payment\_method is boleto). **Boleto** **expire\_date** `string` Expiration date in format YYYY-MM-DD. **digitable\_line** `string` Typed boleto line that will be used by your end customer to pay payin. **bar\_code\_number** `string` Barcode number for the boleto. **agreement** `object` Extra data for billet rendering. **fine** `object` Fine when the expiration date is reached. **discount** `object` Discount when a certain date is reached. **status** `object` Status object. **Status** **id** `integer` Status id. **name** `string` Status name. **status\_history** `array` Status History object. **Status History Item** **status** `object` Status object. **updated\_at** `string` Status update date. **substatus** `object` Sub status object. **Substatus** **id** `integer` The Id of the substatus. **name** `string` The substatus meaning. **reason\_canceled** `object` Reason for the payin cancellation (only appears if the payin was cancelled). **Reason Canceled** **id** `integer` The ID cancellation in our database. Possible values: * `1` - Canceled By Processor * `2` - Canceled By Client **name** `string` The cancellation meaning. Possible values: * `Canceled By Processor` * `Canceled By Client` **kyc** `object` Know your customer object. **KYC** **id** `integer` The KYC ID in our database. **refunds** `array` Refund object. **Refund** **id** `integer` Refund id. **status** `object` Current status of the refund. **amount** `integer` Refund amount. **reason** `string` Free field to inform the reason for the refund. **created\_at** `string` Refund created date. **updated\_at** `string` Refund update date. **automatic\_pix** `object` Automatic Pix configuration (if enabled). **created\_at** `string` Cash-in created date. **updated\_at** `string` Cash-in update date. ## Request Example ```bash cURL theme={null} curl --request GET \ --url https://api.sandbox.wepayout.com.br/v2/payin/payments/32457 \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` ```javascript JavaScript theme={null} async function getChargeById(id) { const response = await fetch( `https://api.sandbox.wepayout.com.br/v2/payin/payments/${id}`, { headers: { 'Accept': 'application/json', 'Authorization': 'Bearer 123' } } ); return await response.json(); } // Usage const charge = await getChargeById(32457); console.log('Charge:', charge); ``` ```python Python theme={null} import requests def get_charge_by_id(charge_id): url = f'https://api.sandbox.wepayout.com.br/v2/payin/payments/{charge_id}' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer 123' } response = requests.get(url, headers=headers) return response.json() # Usage charge = get_charge_by_id(32457) print('Charge:', charge) ``` ```json 200 OK - Pix Charge theme={null} { "id": 51644, "merchant": { "id": 477, "name": "Merchant Name" }, "hash": "bf0976019f5349567a315262cdb4d54e98842061fa26ed0a844c8384a40a58ee", "payment_page": "https://pagar.sandbox.goboleto.com/?hash=bf0976019f5349567a315262cdb4d54e98842061fa26ed0a844c8384a40a58ee", "our_number": "30858", "invoice": "YOUR-INVOICE-1234", "notification_url": "https://your-webhook-url.com/notify", "payment_method": "pix", "amount": 3000, "paid_amount": null, "refunded_amount": 0, "currency": { "id": 19, "name": "Reais", "code": "BRL", "symbol": "R$" }, "description": "Descrição", "created_at": "2025-11-14T17:35:33.000000Z", "updated_at": "2025-11-14T17:35:36.000000Z", "buyer": { "name": "Customer Name", "email": "customer@example.com", "document": { "type": "cnpj", "number": "99999919999979" }, "address": { "country": "BR", "city": null, "street": null, "number": null, "complement": null, "zipcode": null, "district": null, "state_code": null } }, "originator_legal_entity": { "name": "Empresa X", "document": "56251499000164", "helpdesk": "wepayments.com.br" }, "pix": { "expire_date": "2025-12-31 23:59:59", "refund_mode": "FULL_REFUND_MERCHANT", "qr_code": "00020126910014BR.GOV.BCB.PIX2569api-pix-h.bancobs2.com.br/spi/v2/7cc95f1a-743e-4f4a-a3ad-e2ba14f5f6f8520400005303986540510.005802BR5908Wepayout6014Belo Horizonte61083038040362070503***63049F6B", "end_to_end": null, "fine": { "percent": null, "amount": null, "date": null }, "discount": { "percent": null, "amount": null, "date": null } }, "status": { "id": 1, "name": "Created" }, "status_history": [ { "status": { "id": 1, "name": "Created" }, "updated_at": "2025-11-14T17:35:36.000000Z" } ], "substatus": null, "refunds": [], "automatic_pix": null } ``` ```json 200 OK - Canceled Charge theme={null} { "id": 51615, "merchant": { "id": 507, "name": "Merchant Name" }, "hash": "a014e4043acf0631c29dbce842a11a2120ecd8fec71aa8ad72979b0efd26f14a", "payment_page": "https://pagar.sandbox.goboleto.com/?hash=a014e4043acf0631c29dbce842a11a2120ecd8fec71aa8ad72979b0efd26f14a", "our_number": "30831", "invoice": "YOUR-INVOICE-4567", "notification_url": "https://your-webhook-url.com/notify", "payment_method": "pix", "amount": 96728, "paid_amount": null, "refunded_amount": 0, "currency": { "id": 19, "name": "Reais", "code": "BRL", "symbol": "R$" }, "description": "Bill collection", "created_at": "2025-11-14T08:10:29.000000Z", "updated_at": "2025-11-14T08:20:38.000000Z", "buyer": { "name": "Customer Name", "email": "customer@example.com", "document": { "type": "cpf", "number": "34960826312" }, "address": { "country": "BR", "city": null, "street": null, "number": null, "complement": null, "zipcode": null, "district": null, "state_code": null } }, "originator_legal_entity": { "name": "Company Name", "document": "34960826312", "helpdesk": "https://www.company-website.com/" }, "pix": { "expire_date": "2025-11-15 16:10:29", "refund_mode": "FULL_REFUND_MERCHANT", "qr_code": "00020126910014BR.GOV.BCB.PIX2569api-pix-h.bancobs2.com.br/spi/v2/7cc95f1a-743e-4f4a-a3ad-e2ba14f5f6f8520400005303986540510.005802BR5908Wepayout6014Belo Horizonte61083038040362070503***63049F6B", "end_to_end": null, "fine": { "percent": null, "amount": null, "date": null }, "discount": { "percent": null, "amount": null, "date": null } }, "status": { "id": 2, "name": "Canceled" }, "status_history": [ { "status": { "id": 1, "name": "Created" }, "updated_at": "2025-11-14T08:10:31.000000Z" }, { "status": { "id": 2, "name": "Canceled" }, "updated_at": "2025-11-14T08:20:38.000000Z" } ], "substatus": null, "reason_canceled": { "id": 1, "name": "Canceled By Processor" }, "refunds": [], "automatic_pix": null } ``` ```json 404 Not Found theme={null} { "message": "Charge not found" } ``` ## Use Cases > [accordion] Check Payment Status > > Monitor the payment status of a specific charge: > > ```javascript theme={null} > async function checkPaymentStatus(chargeId) { > const charge = await getChargeById(chargeId); > > console.log(`Charge ${charge.invoice}:`); > console.log(`Status: ${charge.status.name}`); > console.log(`Amount: R$ ${charge.amount / 100}`); > console.log(`Paid: R$ ${charge.paid_amount / 100}`); > > return charge.status.id === 4; // 4 = Credited > } > ``` > [accordion] Get QR Code > > Retrieve the Pix QR Code for display: > > ```javascript theme={null} > async function getPixQRCode(chargeId) { > const charge = await getChargeById(chargeId); > > if (charge.payment_method !== 'pix') { > throw new Error('Not a Pix charge'); > } > > return { > qrCode: charge.pix.qr_code, > qrCodeUrl: charge.pix.qr_code_url, > expiresAt: charge.pix.expire_date > }; > } > ``` > [accordion] Get Boleto Details > > Retrieve boleto payment details: > > ```javascript theme={null} > async function getBoletoDetails(chargeId) { > const charge = await getChargeById(chargeId); > > if (charge.payment_method !== 'boleto') { > throw new Error('Not a Boleto charge'); > } > > return { > digitableLine: charge.boleto.digitable_line, > barCode: charge.boleto.bar_code_number, > expiresAt: charge.boleto.expire_date, > ourNumber: charge.our_number > }; > } > ``` > [accordion] Track Status History > > View the complete status history of a charge: > > ```javascript theme={null} > async function getStatusHistory(chargeId) { > const charge = await getChargeById(chargeId); > > console.log(`Status history for charge ${charge.invoice}:`); > charge.status_history.forEach(history => { > console.log(`${history.updated_at}: ${history.status.name}`); > }); > > return charge.status_history; > } > ``` > [accordion] Verify Payment > > Verify if a charge has been paid: > > ```javascript theme={null} > async function verifyPayment(chargeId) { > const charge = await getChargeById(chargeId); > > const isPaid = charge.status.id === 4; > const paidAmount = charge.paid_amount; > const expectedAmount = charge.amount; > > return { > isPaid, > paidAmount, > expectedAmount, > fullyPaid: isPaid && paidAmount >= expectedAmount > }; > } > ``` ## Best Practices > [!NOTE] > > **ID Lookup**: Use the numeric charge ID to retrieve charge details. > [!TIP] > > **Status Monitoring**: Check the `status_history` array to see the complete timeline of status changes for the charge. > [!WARNING] > > **QR Code Expiration**: For Pix charges, always check the `expire_date` before displaying the QR Code to ensure it hasn't expired. # List Charge Source: https://docs.wepayout.co/api-reference/cash-in/payin/list-charge GET /v2/payin/payments List all charges with optional filters # List Charge List all charges with optional filters. ## Query Parameters **merchant\_id** `integer` Merchant id of the account that is creating the payin. Min: `2`, Max: `10000` **invoice** `string` Your identification number. Max length: `255` characters **type\_payin** `string` Payment method used in the payin. Allowed values: `pix`, `boleto` **status\_id** `integer` Filter by status ID. **created\_after** `string` Filter charges created after this date. Format: `YYYY-MM-DD` **created\_before** `string` Filter charges created before this date. Format: `YYYY-MM-DD` **updated\_after** `string` Filter charges updated after this date. Format: `YYYY-MM-DD` **updated\_before** `string` Filter charges updated before this date. Format: `YYYY-MM-DD` **page** `integer` Page number for pagination. Default: `1` **per\_page** `integer` Number of items per page. Default: `15`, Max: `100` **order\_by** `string` Field to sort by. Allowed values: `id`, `created_at`, `updated_at`, `amount` Default: `id` **sort** `string` Sort order. Allowed values: `asc`, `desc` Default: `desc` ## Response Returns an array of charge objects with pagination metadata. **data** `array` Array of charge objects. **Charge Object** **id** `integer` WEpayment's auto generated id. **merchant** `object` Merchant object. **hash** `string` WEpayments auto generated hash. **payment\_page** `string` The WEpayments payment page URL. **our\_number** `string` The bank identification number. **invoice** `string` Your identification number. **notification\_url** `string` The url where we will submit the callbacks. **payment\_method** `string` Payment method: `pix` or `boleto`. **amount** `integer` The payin total amount in cents. **paid\_amount** `integer` The total amount of the payin paid. **refunded\_amount** `integer` Amount refunded from this charge. **description** `string` Instructions displayed to the user. **buyer** `object` The person you are charging object. **originator\_legal\_entity** `object` Final Beneficiary object. **pix** `object` Pix QRCode specific instructions (when payment\_method is pix). **boleto** `object` Boleto specific instructions (when payment\_method is boleto). **status** `object` Status object. **status\_history** `array` Status History object. **substatus** `object` Sub status object. **refunds** `array` Refund object. **created\_at** `string` Cash-in created date. **updated\_at** `string` Cash-in update date. **meta** `object` Pagination metadata. **Pagination** **current\_page** `integer` Current page number. **from** `integer` First item number on current page. **last\_page** `integer` Last page number. **per\_page** `integer` Items per page. **to** `integer` Last item number on current page. **total** `integer` Total number of items. **links** `object` Pagination links. **Links** **first** `string` URL to first page. **last** `string` URL to last page. **prev** `string` URL to previous page (null if on first page). **next** `string` URL to next page (null if on last page). ## Request Example ```bash cURL - All Charges theme={null} curl --request GET \ --url '"https://api.sandbox.wepayout.com.br/v2/payin/payments?page=1&per_page=15"' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` ```bash cURL - Filter by Invoice theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v2/payin/payments?invoice=YOUR-CODE1234' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` ```bash cURL - Filter by Payment Method theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v2/payin/payments?type_payin=pix' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` ```bash cURL - Filter by Date Range theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v2/payin/payments?created_after=2024-01-01&created_before=2024-12-31' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` ```javascript JavaScript theme={null} const params = new URLSearchParams({ page: 1, per_page: 15, type_payin: 'pix', order_by: 'created_at', sort: 'desc' }); const response = await fetch(`https://api.sandbox.wepayout.com.br/v2/payin/payments?${params}`, { method: 'GET', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer 123' } }); const data = await response.json(); console.log(`Total charges: ${data.meta.total}`); console.log(`Current page: ${data.meta.current_page} of ${data.meta.last_page}`); console.log('Charges:', data.data); ``` ```python Python theme={null} import requests params = { 'page': 1, 'per_page': 15, 'type_payin': 'pix', 'order_by': 'created_at', 'sort': 'desc' } headers = { 'Accept': 'application/json', 'Authorization': 'Bearer 123' } response = requests.get( 'https://api.sandbox.wepayout.com.br/v2/payin/payments', params=params, headers=headers ) data = response.json() print(f"Total charges: {data['meta']['total']}") print(f"Current page: {data['meta']['current_page']} of {data['meta']['last_page']}") print('Charges:', data['data']) ``` ```json 200 OK theme={null} { "data": [ { "id": 32457, "merchant": { "id": 1234, "name": "Merchant Name" }, "hash": "885fc0a0fb0e678b82a998daafbc081cbb03c1c862f8e57d580b3b7af152cf47", "payment_page": "https://pagar.sandbox.wepayout.co/?hash=885fc0a0fb0e678b82a998daafbc081cbb03c1c862f8e57d580b3b7af152cf47", "our_number": "20230", "invoice": "YOUR-CODE1234", "notification_url": "https://client.callback.com/notify-payin", "payment_method": "pix", "amount": 5000, "paid_amount": 5000, "refunded_amount": 0, "description": "Esse Pix é referente ao pedido 123 na loja abcd", "created_at": "2024-06-12T23:04:24.000000Z", "updated_at": "2024-06-12T23:04:27.000000Z", "buyer": { "name": "Buyer Name", "email": "buyer-email@wepayments.com.br", "document": { "type": "CPF", "number": "34960826312" } }, "status": { "id": 4, "name": "Credited" } } ], "meta": { "current_page": 1, "from": 1, "last_page": 5, "per_page": 15, "to": 15, "total": 73 }, "links": { "first": "https://api.sandbox.wepayout.com.br/v2/payin/payments?page=1", "last": "https://api.sandbox.wepayout.com.br/v2/payin/payments?page=5", "prev": null, "next": "https://api.sandbox.wepayout.com.br/v2/payin/payments?page=2" } } ``` ## Use Cases > [accordion] List All Charges > > Retrieve all charges with pagination: > > ```javascript theme={null} > async function getAllCharges(page = 1, perPage = 15) { > const response = await fetch( > `https://api.sandbox.wepayout.com.br/v2/payin/payments?page=${page}&per_page=${perPage}`, > { > headers: { > 'Authorization': 'Bearer YOUR_TOKEN', > 'Accept': 'application/json' > } > } > ); > > return await response.json(); > } > ``` > [accordion] Filter by Status > > Get charges by specific status: > > ```javascript theme={null} > async function getChargesByStatus(statusId) { > const response = await fetch( > `https://api.sandbox.wepayout.com.br/v2/payin/payments?status_id=${statusId}`, > { > headers: { > 'Authorization': 'Bearer YOUR_TOKEN', > 'Accept': 'application/json' > } > } > ); > > return await response.json(); > } > > // Get credited charges (status_id = 4) > const paidCharges = await getChargesByStatus(4); > ``` > [accordion] Search by Invoice > > Find a specific charge by invoice number: > > ```javascript theme={null} > async function findChargeByInvoice(invoice) { > const response = await fetch( > `https://api.sandbox.wepayout.com.br/v2/payin/payments?invoice=${invoice}`, > { > headers: { > 'Authorization': 'Bearer YOUR_TOKEN', > 'Accept': 'application/json' > } > } > ); > > const data = await response.json(); > return data.data[0]; // Return first match > } > ``` > [accordion] Date Range Report > > Generate a report for a specific date range: > > ```javascript theme={null} > async function getChargesReport(startDate, endDate) { > const params = new URLSearchParams({ > created_after: startDate, > created_before: endDate, > per_page: 100, > order_by: 'created_at', > sort: 'asc' > }); > > const response = await fetch( > `https://api.sandbox.wepayout.com.br/v2/payin/payments?${params}`, > { > headers: { > 'Authorization': 'Bearer YOUR_TOKEN', > 'Accept': 'application/json' > } > } > ); > > return await response.json(); > } > > // Get charges from January 2024 > const report = await getChargesReport('2024-01-01', '2024-01-31'); > ``` > [accordion] Pagination Handler > > Handle pagination to retrieve all charges: > > ```javascript theme={null} > async function getAllChargesWithPagination() { > let allCharges = []; > let currentPage = 1; > let hasMorePages = true; > > while (hasMorePages) { > const response = await fetch( > `https://api.sandbox.wepayout.com.br/v2/payin/payments?page=${currentPage}&per_page=100`, > { > headers: { > 'Authorization': 'Bearer YOUR_TOKEN', > 'Accept': 'application/json' > } > } > ); > > const data = await response.json(); > allCharges = allCharges.concat(data.data); > > hasMorePages = data.meta.current_page < data.meta.last_page; > currentPage++; > } > > return allCharges; > } > ``` ## Status IDs Common status IDs for filtering: | ID | Status Name | Description | | - | - | - | | 1 | Created | Charge has been created | | 2 | Canceled | Charge canceled due to expiration | | 3 | Paid | Charge successfully paid | | 4 | Credited | Amount is paid and available for withdrawal | | 5 | Drop\_requested | Cancellation requested | | 7 | Rejected | Charge rejected due to compliance | ## Best Practices > [!NOTE] > > **Pagination**: Always use pagination when listing charges to avoid performance issues. The default page size is 15, with a maximum of 100 items per page. > [!WARNING] > > **Date Filters**: When using date range filters, ensure the range is not too large to avoid timeouts. For large date ranges, consider breaking them into smaller chunks. > [!TIP] > > **Caching**: Consider caching the results for frequently accessed pages to reduce API calls and improve performance. # Cancel Charges Source: https://docs.wepayout.co/api-reference/cash-in/payin/request-multiple-cancel DELETE /v2/payin/payments/request-multiple-cancel Request the cancellation of Payins by a list of IDs # Cancel Charges Request the asynchronous cancellation of one or more Payins (`billet` or `pix`) by sending a list of their IDs. > [!NOTE] > > This is an **asynchronous** request. A `202 Accepted` response means the eligible charges were **queued** for cancellation, not that they were already canceled. Each eligible charge is processed by a background job. ## Eligibility > [!WARNING] > > **Cancellation Restrictions** — an ID is only queued for cancellation when the charge: > > * has `status = created` > * is of type `pix` or `billet` (credit-card charges are never eligible) > * respects the minimum time since creation (see below) > > IDs that are not found or not eligible are returned grouped under `errors`; they are **not** canceled. ## Minimum Time Before Cancellation * **pix**: at least 5 minutes after creation * **billet**: at least 30 minutes after creation ## Request Body **ids** `array` *required* A list of Payin (charge) IDs to cancel. * Minimum: **1** item * Maximum: **200** items Example: `[32457, 32458, 32459]` ## Response The response body is returned **as-is** (it does not use the standard `status`/`data` envelope). **send** `array` The IDs that were accepted and queued for cancellation. **errors** `object` A map keyed by the reason an ID could not be queued, each pointing to the list of affected IDs (e.g. not found, wrong status, minimum time not met, not a pix/billet charge). ## Request Example ```bash cURL theme={null} curl --request DELETE \ --url https://api.sandbox.wepayout.com.br/v2/payin/payments/request-multiple-cancel \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' \ --header 'Content-Type: application/json' \ --data '{ "ids": [32457, 32458, 32459] }' ``` ```javascript JavaScript theme={null} async function cancelCharges(ids) { const response = await fetch( 'https://api.sandbox.wepayout.com.br/v2/payin/payments/request-multiple-cancel', { method: 'DELETE', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer 123', 'Content-Type': 'application/json' }, body: JSON.stringify({ ids }) } ); return await response.json(); } // Usage — between 1 and 200 IDs const ids = [32457, 32458, 32459]; const result = await cancelCharges(ids); console.log('Cancellation result:', result); ``` ```python Python theme={null} import requests def cancel_charges(ids): url = 'https://api.sandbox.wepayout.com.br/v2/payin/payments/request-multiple-cancel' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer 123', 'Content-Type': 'application/json' } data = {'ids': ids} response = requests.delete(url, headers=headers, json=data) return response.json() # Usage — between 1 and 200 IDs ids = [32457, 32458, 32459] result = cancel_charges(ids) print('Cancellation result:', result) ``` ```json 202 Accepted theme={null} { "send": [32457, 32458, 32459], "errors": { "Charge status must be 'created' to be canceled": [32460, 32461], "Charge not found": [32462] } } ``` ```json 422 Unprocessable Entity theme={null} { "message": "The given data was invalid.", "errors": { "ids": [ "The ids field is required." ] } } ``` ```json 500 Internal Server Error theme={null} { "message": "Unable to request the cancellation." } ``` ## Important Notes > [!NOTE] > > **Pix Cancellation**: Pix charges are canceled instantly once the job runs. > [!WARNING] > > **Billet Cancellation**: Billet charges require at least 1 day to move from `drop_requested` to `canceled`, as the process depends on confirmation from the payment processor. > [!TIP] > > Send between **1 and 200** IDs per request. To cancel every charge of a merchant within a date range, use [Cancel Charges by Period](/api-reference/cash-in/payin/cancel-by-period) instead. # Create Refund Source: https://docs.wepayout.co/api-reference/cash-in/refund/create-refund POST /v2/payin/payments/payin-refund/{id} Create a new refund. To initiate the refund, you must provide the unique identifier of the Pix or credit card payment in the {id} parameter. ## Some important rules > [!WARNING] > > * Only charges **credited to the wallet** can be refunded. > * The wallet(s) being debited must have at least the **refund amount available**. See [Which wallet is debited](#which-wallet-is-debited). > * **Pix**: can only be returned with **90 days or less**. > * **Credit card**: **180 days or less**. ## Sandbox Testing > [!NOTE] > > To test refund scenarios in the sandbox environment, the field `amount` must be one of the following values: **100**, **1000**, or **10000**. > > Additionally, you must include the field `reason` with the value **"APRO"**. ## Which wallet is debited For Pix charges, the wallet debited by the refund is defined by the `pix.refund_mode` sent when the charge was created (see [Create Charge (Pix)](/api-reference/cash-in/payin/create-charge-pix)): | `refund_mode` | Wallet debited | | - | - | | `FULL_REFUND_MERCHANT` (default) | The wallet of the merchant that created the charge, even if the charge has splits. | | `FULL_REFUND_RECIPIENT` | The wallet that received the split. If the charge has more than one wallet in `splits`, the refund is rejected. | | `REFUND_BY_SPLIT` | The wallets informed in the `splits` field of this request, which is mandatory in this mode. | > [!NOTE] > > Regardless of the `refund_mode`, a refund request that informs `splits` debits the wallets listed in it. Use it to debit a split wallet when the charge was created without `refund_mode`. The balance of every wallet being debited is checked before the refund is created. If any of them does not cover its part, the request is rejected with HTTP `400` and no refund is created. ## Path Parameters **id** `integer` *required* The cash-in ID (payin ID) for which the refund will be created. Example: `63730` ## Request Body **amount** `integer` *required* The refund amount in the smallest currency unit (e.g., `1000` to refund R\$10.00). Example: `1000` **reason** `string` *required* Reason for the refund. Example: `"Teste"` **notification\_url** `string` URL to receive webhook notifications about refund status changes. **splits** `array` Wallets to be debited by this refund. Mandatory when the charge was created with `refund_mode` = `REFUND_BY_SPLIT`. See [Which wallet is debited](#which-wallet-is-debited). The sum of the splits cannot be greater than the refund `amount`. Any remaining amount is debited from the wallet of the merchant that created the charge. **Split Object** **wallet\_uuid** `string` *required* UUID of the wallet to be debited. It must be one of the wallets in the `splits` of the charge, and cannot be repeated in the list. **amount** `integer` Amount to debit from this wallet, in the smallest currency unit (e.g., `1000` for R\$10.00). Required if `percent` is not provided. Cannot be sent together with `percent`. Min: `1` **percent** `number` Percentage of the **refund amount** to debit from this wallet. Required if `amount` is not provided. Cannot be sent together with `amount`. Min: `0.01`, Max: `100` ```bash By amount theme={null} curl --location 'https://api.sandbox.wepayout.co/v2/payin/payments/payin-refund/63730' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_TOKEN_HERE' \ --data-raw '{ "amount": 1000, "reason": "Customer requested cancellation", "splits": [ { "wallet_uuid": "WALLET_UUID", "amount": 1000 } ] }' ``` ```bash By percent theme={null} curl --location 'https://api.sandbox.wepayout.co/v2/payin/payments/payin-refund/63730' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_TOKEN_HERE' \ --data-raw '{ "amount": 1000, "reason": "Customer requested cancellation", "splits": [ { "wallet_uuid": "WALLET_UUID", "percent": 50 } ] }' ``` > [!NOTE] > > In the **By percent** example, R\$5.00 (50% of the refund) is debited from the split wallet and the remaining R\$5.00 from the merchant wallet. ## Response **id** `integer` Refund ID. **payin\_id** `integer` The ID of the payin (cash-in) being refunded. **status\_id** `integer` Current status ID of the refund. Status codes: * `2`: Requested * `4`: Paid (refund completed) * `5`: Error **user** `object` User who created the refund. **User** **id** `integer` User ID. **name** `string` User name. **client\_id** `integer` Client ID. **refund\_amount** `integer` Refund amount. **status\_history** `array` History of status changes. **Status History Item** **id** `integer` Status history ID. **status\_id** `integer` Status ID. **name** `string` Status name. **notification** `integer` Notification flag. **created\_at** `string` When this status was set. **end\_to\_end\_id** `string` End-to-end ID (for Pix transactions). Can be `null`. **reason** `string` Reason for the refund. **wallet\_error\_code** `string` Error code from wallet (if any). Can be `null`. **notification\_url** `string` URL for webhook notifications. Can be `null`. **created\_at** `string` Refund created date. **updated\_at** `string` Refund update date. ```json 200 theme={null} { "id": 123, "payin_id": 456, "status_id": 2, "user": { "id": 789, "name": "João Silva" }, "client_id": 10, "refund_amount": 10000, "status_history": [ { "id": 1, "payin_refund_id": 123, "statusId": 1, "status_id": 1, "name": "Check", "notification": 1, "created_at": "2026-02-19T12:34:56.000000Z" } ], "end_to_end_id": "E12345678202602191234567890AB", "reason": "Customer requested cancellation", "wallet_error_code": null, "notification_url": "https://example.com/webhook", "created_at": "2026-02-19T12:34:56.000000Z", "updated_at": "2026-02-19T12:34:56.000000Z" } ``` ```json 400 theme={null} { "message": "Insufficient balance" } ``` ```json 401 theme={null} { "error": "Unauthorized" } ``` ```json 404 theme={null} { "message": "Payin not found" } ``` ```json 422 theme={null} { "message": "The given data was invalid.", "errors": { "amount": [ "The amount field is required." ] } } ``` ```json 500 Internal server error theme={null} { "error": "Internal server error" } ``` ## Errors related to the debited wallet | HTTP | Message | When | | - | - | - | | `400` | `Insufficient balance` | A wallet being debited does not have the refund amount (or its part of it) available. | | `400` | `Refund of sub-wallet or sub merchante discounted charges, not possible for charges with more than one sub-wallet or sub merchant.` | The charge uses `FULL_REFUND_RECIPIENT` and has more than one wallet in `splits`. | | `400` | `This charge cannot be reversed` | The charge uses `REFUND_BY_SPLIT` and the request has no `splits`. | | `422` | `One or more recipients does not belongs to the Payin charge` | A `splits[].wallet_uuid` is not one of the wallets in the `splits` of the charge. | | `422` | `The sum of the splits amount cannot be greater than the refund amount` | The sum of `splits` is greater than the refund `amount`. | ## Important Information About the Webhook metadata ### Refund Status | Status | Description | Status ID | | - | - | - | | Requested | The refund has been requested. | 2 | | Paid | The refund has been successfully paid. | 4 | | Error | An error occurred during the refund process. | 5 | > [!WARNING] > > If an error occurs during the refund process (status 5), the field `total_refund_amount` will be **decremented** by the requested amount. When the refund is successfully paid, the amount will be **incremented** again. ### Webhook Payload Examples: **Requested:** ```json theme={null} { "id": 123, "payin_id": 456, "status": { "id": 2, "name": "Requested" }, "metadata": { "refund_amount": 100.50, "total_refund_amount": 250.75 }, "reason": "Customer requested cancellation", "updated_at": "2026-02-19T12:34:56.000000Z" } ``` **Error:** ```json theme={null} { "id": 123, "payin_id": 456, "status": { "id": 5, "name": "Error" }, "metadata": { "refund_amount": 100.50, "total_refund_amount": 150.25 }, "reason": "Customer requested cancellation", "updated_at": "2026-02-19T12:35:10.000000Z" } ``` **Paid:** ```json theme={null} { "id": 123, "payin_id": 456, "status": { "id": 4, "name": "Paid" }, "metadata": { "refund_amount": 100.50, "total_refund_amount": 250.75 }, "reason": "Customer requested cancellation", "updated_at": "2026-02-19T12:36:22.000000Z" } ``` ## Refund Status Flow **Success scenario:** ``` REQUESTED (2) → PAID (4) ✓ ``` **Error scenario:** ``` REQUESTED (2) → ERROR (5) ✗ ``` # Get Unique Refund Source: https://docs.wepayout.co/api-reference/cash-in/refund/get-unique-refund GET /v1/payin/payments/payin-refund/{refundId} Returns the refund using its unique identifier # Get Unique Refund Returns the refund using its unique identifier. ## Path Parameters **refundId** `integer` *required* The unique ID of the refund to retrieve. Example: `1234` ## Response **id** `integer` Refund ID. **payin\_id** `integer` ID of the payin (payin) that was refunded. **status\_id** `integer` Current status of the refund. Status codes: * `2`: REQUESTED * `4`: PAID (refund completed) * `5`: ERROR **user** `object` User object. **User** **id** `integer` User ID who made the refund request. **name** `string` User name who made the refund request. **status\_id** `integer` Refund status ID. **name** `string` Refund status name. **notification** `string` Notification message. **created\_at** `string` Creation date time. **end\_to\_end\_id** `string` End-to-end ID (Pix transaction identifier). **reason** `string` Reason for the refund. **wallet\_error\_code** `string` Wallet error code (if applicable). **notification\_url** `string` Payin where notification will be sent. **created\_at** `string` Creation date time. **updated\_at** `string` Update date time. **refund\_amount** `integer` Refund value in cents. **status\_history** `array` Array of status history. **Status History Item** **id** `integer` Unique ID. **status\_id** `integer` Status ID. **name** `string` Status name. **notification** `string` Notification. **created\_at** `string` Creation date time. **end\_to\_end\_id** `string` End-to-end ID. ## Request Example ```bash cURL theme={null} curl --request GET \ --url https://api.sandbox.wepayout.com.br/v1/payin/payments/payin-refund/1234 \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` ```javascript JavaScript theme={null} async function getRefund(refundId) { const response = await fetch( `https://api.sandbox.wepayout.com.br/v1/payin/payments/payin-refund/${refundId}`, { method: 'GET', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer 123' } } ); return await response.json(); } // Usage const refund = await getRefund(1234); console.log('Refund details:', refund); console.log('Status:', refund.name); console.log('Amount:', refund.refund_amount / 100); ``` ```python Python theme={null} import requests def get_refund(refund_id): url = f'https://api.sandbox.wepayout.com.br/v1/payin/payments/payin-refund/{refund_id}' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer 123' } response = requests.get(url, headers=headers) return response.json() # Usage refund = get_refund(1234) print(f"Refund details: {refund}") print(f"Status: {refund['name']}") print(f"Amount: R$ {refund['refund_amount'] / 100}") ``` ```json 200 OK theme={null} { "id": 12345, "payin_id": 32457, "status_id": 4, "user": { "id": 1, "name": "Admin User" }, "name": "PAID", "notification": "string", "created_at": "2024-06-12T23:10:00.000000Z", "end_to_end_id": "E1805820220621234567890AB1C2", "reason": "Customer requested refund", "wallet_error_code": null, "notification_url": "https://client.callback.com/notify-payin", "updated_at": "2024-06-12T23:15:00.000000Z", "refund_amount": 5000, "status_history": [ { "id": 1, "status_id": 2, "name": "REQUESTED", "notification": "Refund requested", "created_at": "2024-06-12T23:10:00.000000Z", "end_to_end_id": null }, { "id": 2, "status_id": 4, "name": "PAID", "notification": "Refund completed", "created_at": "2024-06-12T23:15:00.000000Z", "end_to_end_id": "E1805820220621234567890AB1C2" } ] } ``` ```json 404 Not Found theme={null} { "message": "Refund not found" } ``` ## Use Cases > [accordion] Check Refund Status > > Monitor the status of a refund: > > ```javascript theme={null} > async function checkRefundStatus(refundId) { > const refund = await getRefund(refundId); > > const statusMap = { > 2: 'REQUESTED - Refund is being processed', > 4: 'PAID - Refund completed successfully', > 5: 'ERROR - Refund failed' > }; > > console.log(`Refund ${refundId}:`); > console.log(`Status: ${statusMap[refund.status_id]}`); > console.log(`Amount: R$ ${refund.refund_amount / 100}`); > console.log(`Reason: ${refund.reason}`); > > return refund.status_id === 4; > } > ``` > [accordion] Track Refund History > > View the complete history of a refund: > > ```javascript theme={null} > async function trackRefundHistory(refundId) { > const refund = await getRefund(refundId); > > console.log(`Refund history for ID ${refundId}:`); > refund.status_history.forEach(history => { > console.log(`${history.created_at}: ${history.name} - ${history.notification}`); > }); > > return refund.status_history; > } > ``` > [accordion] Verify Refund Completion > > Check if a refund has been completed: > > ```javascript theme={null} > async function verifyRefundCompletion(refundId) { > const refund = await getRefund(refundId); > > const isCompleted = refund.status_id === 4; > const hasFailed = refund.status_id === 5; > > if (isCompleted) { > console.log(`Refund completed successfully`); > console.log(`End-to-end ID: ${refund.end_to_end_id}`); > return true; > } > > if (hasFailed) { > console.log(`Refund failed`); > console.log(`Error: ${refund.wallet_error_code}`); > return false; > } > > console.log(`Refund still processing`); > return null; > } > ``` > [accordion] Get Refund Details for Reconciliation > > Retrieve refund details for accounting reconciliation: > > ```javascript theme={null} > async function getRefundForReconciliation(refundId) { > const refund = await getRefund(refundId); > > return { > refundId: refund.id, > payinId: refund.payin_id, > amount: refund.refund_amount / 100, > status: refund.name, > endToEndId: refund.end_to_end_id, > reason: refund.reason, > createdAt: refund.created_at, > completedAt: refund.updated_at, > user: refund.user.name > }; > } > > // Usage > const reconciliation = await getRefundForReconciliation(1234); > console.log('Reconciliation data:', reconciliation); > ``` > [accordion] Monitor Multiple Refunds > > Check status of multiple refunds: > > ```javascript theme={null} > async function monitorRefunds(refundIds) { > const results = []; > > for (const refundId of refundIds) { > try { > const refund = await getRefund(refundId); > results.push({ > id: refundId, > status: refund.name, > amount: refund.refund_amount, > completed: refund.status_id === 4 > }); > } catch (error) { > results.push({ > id: refundId, > error: error.message > }); > } > } > > return results; > } > > // Usage > const refundIds = [1234, 1235, 1236]; > const statuses = await monitorRefunds(refundIds); > console.log('Refund statuses:', statuses); > ``` ## Status Codes | Status ID | Status Name | Description | | - | - | - | | 2 | REQUESTED | Refund has been requested and is being processed | | 4 | PAID | Refund has been completed successfully | | 5 | ERROR | Refund has failed | ## Best Practices > [!NOTE] > > **Status History**: Use the `status_history` array to track the complete timeline of the refund process. > [!TIP] > > **End-to-End ID**: The `end_to_end_id` is only available after the refund is completed (status = PAID). Use it for Pix transaction tracking. > [!WARNING] > > **Error Handling**: Always check the `wallet_error_code` field when status is ERROR to understand why the refund failed. # Resend Payin Webhooks (Bulk) Source: https://docs.wepayout.co/api-reference/cash-in/webhooks/resend-bulk POST /v2/payin/notifications/resend Dispatch a bulk job to resend payin webhook notifications for a given merchant and time range ## Overview This endpoint allows you to resend webhook notifications in bulk for payin transactions within a specified time window. It dispatches an asynchronous job and returns a `job_id` that can be used to track progress via the [Job Status](/api-reference/cash-in/webhooks/resend-bulk-status) endpoint. > [!NOTE] > > The time range is limited to a maximum of **3 hours** between `start_time` and `end_time`. > [!WARNING] > > Only one resend job can run at a time per merchant and start time. If a job is already running for the same merchant and start time, the request will return `409 Conflict`. ## Request Body **merchant\_id** `integer` *required* The ID of the merchant whose payin notifications will be resent. Must be one of the merchant IDs associated with your account. **start\_time** `string` *required* Start of the time range for filtering payin transactions. Format: `YYYY-MM-DD HH:MM:SS` Example: `"2026-03-24 08:00:00"` **end\_time** `string` *required* End of the time range for filtering payin transactions. Must be after `start_time`. Maximum range: **3 hours** from `start_time`. Format: `YYYY-MM-DD HH:MM:SS` Example: `"2026-03-24 11:00:00"` **status\_ids** `array` Optional list of status IDs to filter which payin transactions will have notifications resent. If omitted, all notifiable statuses are included. Notifiable status IDs: | ID | Status | | - | - | | 2 | Canceled | | 3 | Paid | | 4 | Credited | | 5 | Drop Requested | | 6 | Awaiting Approval | | 7 | Rejected | | 8 | Confirmed | | 9 | Partial Credited | | 10 | Pending Challenge | Example: `[3, 4]` **dry\_run** `boolean` When `true`, the job is **not dispatched**. Instead, only the count of matching transactions is returned. Useful for estimating volume before triggering the actual resend. Default: `false` ## Response **job\_id** `string` Unique identifier for the dispatched job. Use this to query the job status. Example: `"a3f1bc2e4d8f0a1b2c3d4e5f6a7b8c9d"` **total** `integer` Total number of payin transactions matched and queued for webhook resend. Example: `142` ```json 202 theme={null} { "job_id": "a3f1bc2e4d8f0a1b2c3d4e5f6a7b8c9d", "total": 142 } ``` ```json 200 (dry_run) theme={null} { "total": 142 } ``` ```json 409 theme={null} { "message": "A resend job is already running for this merchant and time range." } ``` ```json 422 theme={null} { "message": "Validation error.", "errors": { "end_time": [ "The time range must not exceed 3 hours." ] } } ``` ## Code Examples ```bash cURL theme={null} curl -X POST "https://api.wepayments.com/v2/payin/notifications/resend" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "merchant_id": 303, "start_time": "2026-03-24 08:00:00", "end_time": "2026-03-24 11:00:00", "status_ids": [3, 4], "dry_run": false }' ``` ```javascript JavaScript theme={null} const response = await fetch('https://api.wepayments.com/v2/payin/notifications/resend', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ merchant_id: 303, start_time: '2026-03-24 08:00:00', end_time: '2026-03-24 11:00:00', status_ids: [3, 4], dry_run: false }) }); const { job_id, total } = await response.json(); console.log(`Job dispatched: ${job_id} (${total} transactions)`); ``` ```python Python theme={null} import requests response = requests.post( 'https://api.wepayments.com/v2/payin/notifications/resend', headers={'Authorization': 'Bearer YOUR_API_KEY'}, json={ 'merchant_id': 303, 'start_time': '2026-03-24 08:00:00', 'end_time': '2026-03-24 11:00:00', 'status_ids': [3, 4], 'dry_run': False } ) data = response.json() print(f"Job dispatched: {data['job_id']} ({data['total']} transactions)") ``` ```php PHP theme={null} 303, 'start_time' => '2026-03-24 08:00:00', 'end_time' => '2026-03-24 11:00:00', 'status_ids' => [3, 4], 'dry_run' => false ])); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = json_decode(curl_exec($ch), true); curl_close($ch); echo "Job dispatched: {$response['job_id']} ({$response['total']} transactions)"; ?> ``` ## Related > [card] [Job Status](/api-reference/cash-in/webhooks/resend-bulk-status) > > Track the progress of a dispatched resend job > [card] [Payin Webhook](/cash-in/payin-webhook) > > Understand the webhook payload structure > [card] [Status Flow](/cash-in/status-flow) > > Understand payin status lifecycle # Resend Job Status Source: https://docs.wepayout.co/api-reference/cash-in/webhooks/resend-bulk-status GET /v2/payin/notifications/resend/{jobId} Check the progress and status of a bulk payin webhook resend job ## Overview After dispatching a bulk resend job via [Resend Payin Webhooks (Bulk)](/api-reference/cash-in/webhooks/resend-bulk), use this endpoint to monitor its progress. Job state is available for **24 hours** after completion. ## Path Parameters **jobId** `string` *required* The job ID returned by the [bulk resend endpoint](/api-reference/cash-in/webhooks/resend-bulk). Example: `"a3f1bc2e4d8f0a1b2c3d4e5f6a7b8c9d"` ## Response **status** `string` Current status of the job. | Value | Description | | - | - | | `processing` | Job is running — transactions are being queued | | `completed` | Job finished successfully | | `failed` | Job encountered a fatal error and was aborted | **merchant\_id** `integer` ID of the merchant for which the resend was triggered. Example: `303` **start\_time** `string` Start of the time range used in the original request. Example: `"2026-03-24 08:00:00"` **end\_time** `string` End of the time range used in the original request. Example: `"2026-03-24 11:00:00"` **total** `integer` Total number of payin transactions matched at the time of dispatch. Example: `142` **queued** `integer` Number of webhook notifications successfully enqueued so far. Example: `98` **failed** `integer` Number of webhook notifications that failed to be enqueued. Example: `2` **started\_at** `string` ISO 8601 timestamp of when the job started. Example: `"2026-03-24T08:05:00+00:00"` **updated\_at** `string` ISO 8601 timestamp of the last state update. Example: `"2026-03-24T08:07:32+00:00"` **reason** `string` Present only when `status` is `failed`. Describes the fatal error that caused the job to abort. Example: `"Connection refused"` ```json 200 (processing) theme={null} { "status": "processing", "merchant_id": 303, "start_time": "2026-03-24 08:00:00", "end_time": "2026-03-24 11:00:00", "total": 142, "queued": 98, "failed": 0, "started_at": "2026-03-24T08:05:00+00:00", "updated_at": "2026-03-24T08:07:32+00:00" } ``` ```json 200 (completed) theme={null} { "status": "completed", "merchant_id": 303, "start_time": "2026-03-24 08:00:00", "end_time": "2026-03-24 11:00:00", "total": 142, "queued": 140, "failed": 2, "started_at": "2026-03-24T08:05:00+00:00", "updated_at": "2026-03-24T08:09:15+00:00" } ``` ```json 200 (failed) theme={null} { "status": "failed", "merchant_id": 303, "start_time": "2026-03-24 08:00:00", "end_time": "2026-03-24 11:00:00", "total": 142, "queued": 0, "failed": 0, "started_at": "2026-03-24T08:05:00+00:00", "updated_at": "2026-03-24T08:05:03+00:00", "reason": "Connection refused" } ``` ```json 404 theme={null} { "message": "Job not found." } ``` ```json 403 theme={null} { "message": "Forbidden" } ``` ## Code Examples ```bash cURL theme={null} curl -X GET "https://api.wepayments.com/v2/payin/notifications/resend/a3f1bc2e4d8f0a1b2c3d4e5f6a7b8c9d" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```javascript JavaScript theme={null} const jobId = 'a3f1bc2e4d8f0a1b2c3d4e5f6a7b8c9d'; const response = await fetch( `https://api.wepayments.com/v2/payin/notifications/resend/${jobId}`, { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ); const job = await response.json(); console.log(`Status: ${job.status} — queued: ${job.queued}/${job.total}`); ``` ```python Python theme={null} import requests job_id = 'a3f1bc2e4d8f0a1b2c3d4e5f6a7b8c9d' response = requests.get( f'https://api.wepayments.com/v2/payin/notifications/resend/{job_id}', headers={'Authorization': 'Bearer YOUR_API_KEY'} ) job = response.json() print(f"Status: {job['status']} — queued: {job['queued']}/{job['total']}") ``` ```php PHP theme={null} ``` ## Polling the Job Job state is updated in real-time as the job processes each chunk of 200 transactions. A simple polling pattern: ```javascript theme={null} async function waitForJob(jobId, intervalMs = 3000) { while (true) { const res = await fetch( `https://api.wepayments.com/v2/payin/notifications/resend/${jobId}`, { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ); const job = await res.json(); console.log(`[${job.status}] queued: ${job.queued}/${job.total}, failed: ${job.failed}`); if (job.status === 'completed' || job.status === 'failed') { return job; } await new Promise(resolve => setTimeout(resolve, intervalMs)); } } ``` > [!NOTE] > > Job state is stored for **24 hours**. After that, the endpoint will return `404`. ## Related > [card] [Resend Webhooks (Bulk)](/api-reference/cash-in/webhooks/resend-bulk) > > Dispatch a new bulk resend job > [card] [Payin Webhook](/cash-in/payin-webhook) > > Understand the webhook payload structure # Create Payment Source: https://docs.wepayout.co/api-reference/cash-out/payout/create-payment POST /v2/payout/payments Create a new payout payment to transfer funds ## Request Body **merchant\_id** `integer` Merchant id of the account that is creating the payout. The custom number will be different for sandbox and production environment. Is mandatory if there is more than one account under your umbrella (sellers). **payment\_method** `string` *required* Payment method for the payout. Allowed values: `PIX`, `QRCODE` Use `QRCODE` to pay a third-party PIX QR Code decoded at the [Decode QR Code](/api-reference/cash-out/payout/decode-qr-code) endpoint. **currency** `string` *required* Currency code of the amount (ISO 4217). Example: `BRL` **country** `string` *required* Country code (ISO 3166-1 alpha-2). Example: `BR` **amount** `number` *required* The payout amount in decimal format. Example: `50.34` **invoice** `string` *required* Unique invoice identifier (UUID format recommended). Example: `e3317882-f821-455b-b082-dc3ba36e8a57` **description** `string` Description or purpose of the payout. Max length: `255` characters **beneficiary** `object` Beneficiary information. Required unless `payment_method` is `QRCODE`: in that case the beneficiary comes from the decoded QR Code. **Beneficiary Object** **name** `string` *required* Beneficiary's full name. Max length: `100` characters **document** `object` *required* Beneficiary's document. **Document Object** **type** `string` *required* Document type. Allowed values: `CPF`, `CNPJ` **number** `string` *required* Document number (digits only). **birthdate** `string` Beneficiary's birthdate in format `YYYY-MM-DD`. **phone** `string` Beneficiary's phone number. **address** `object` Beneficiary's address information. **Address Object** **address** `string` Street address. **city** `string` City name. **country** `string` Country code. **state\_code** `string` State code. **zip\_code** `string` ZIP/Postal code. **remitter** `object` Details of remitter. Mandatory for the remittance model. Payments from individuals to individuals. The remitter's name and date of birth are not sent: they are filled from the CPF while the payout is processed. If the CPF is not active at the Brazilian Federal Revenue (Receita Federal), the payout is canceled with code `57`; if it cannot be validated, with code `58`. See [Rejection Reasons](/cash-out/rejection-reasons). **Remitter Object** **document** `string` *required* CPF of who is sending the payment (cash). Must be a valid CPF; the mask is optional. Example: `123.456.789-09` or `12345678909` **country** `string` *required* Country of who is sending the payment (cash). Format: ISO 3166-1 alpha-2 (2 characters) Example: `US` **originator\_legal\_entity** `object` Legal entity information of the payment originator. Mandatory for crossborder merchants. **Originator Legal Entity Object** **name** `string` *required* Legal entity name of the originator. Max length: `125` characters **website** `string` *required* Legal entity website of the originator. Max length: `125` characters **pix** `object` PIX payment information. Required when `payment_method` is `PIX`. Use either `pix_key` OR bank account details. **PIX Object** **pix\_key** `string` PIX key (CPF, CNPJ, email, phone, or random key). Use this for payments via PIX key. Send the key without masks. Phone keys must be a Brazilian mobile number with exactly 14 characters (`+55` + area code + `9` + 8 digits, e.g. `+5551966084315`), and e-mail keys can have up to 77 characters. See [Accepted PIX key formats](/cash-out/about-payments#accepted-pix-key-formats). **Note**: When using `pix_key`, bank account fields are not required. **ispb** `string` ISPB of the beneficiary's institution. Required when using bank account details. Exactly 8 digits, e.g. `18236120`. The ISPB must be in the [list of institutions](/api-reference/banks/list-institutions). **bank\_branch** `string` Branch number (agência), **without the branch check digit**. Required when using bank account details. Digits only, 1 to 5 characters, e.g. `0001`. **bank\_branch\_digit** `string` Branch check digit, when the branch has one. Optional. Up to 2 characters. **account** `string` Account number **without the check digit and without the hyphen**. Required when using bank account details. Up to 20 characters. For account `823250233-4`, send `823250233`. **account\_digit** `string` Account check digit: the character **after the hyphen** in the account number. Required when using bank account details. Exactly 1 character. For account `823250233-4`, send `4`. Do not move the last digit of the account number into this field: if the account is `823250233-4`, sending `account: "82325023"` and `account_digit: "3"` points to an account that does not exist, and the payment is rejected with status detail `8` (Wrong bank account). **account\_type** `string` Account type. Required when using bank account details. Allowed values: `CHECKING`, `SAVINGS` (the ISO codes `CACC` and `SVGS` are also accepted). For payment accounts (contas de pagamento, as in digital banks), use `CHECKING`. **qrcode** `object` QR Code payment information. Required when `payment_method` is `QRCODE`. **QR Code Object** **end\_to\_end\_id** `string` *required* `end_to_end_id` returned by the [Decode QR Code](/api-reference/cash-out/payout/decode-qr-code) endpoint. It expires 5 minutes after the decode and can be used for a single payment. Max length: `255` characters When the decoded QR Code has `is_amount_changeable` equal to `false`, `amount` must be equal to the QR Code amount. **notification\_url** `string` URL where webhook notifications will be sent. Max length: `255` characters **purpose** `string` Purpose code for the transaction. Default: `20` **receipt\_message** `string` Custom message to appear on the receipt. ## Response **id** `integer` WEpayment's auto generated payout ID. **merchant** `object` Merchant information. **Merchant** **id** `integer` Merchant ID. **name** `string` Merchant name. **payment\_method** `string` Payment method used. **country** `string` Country code. **currency** `string` Currency code. **amount** `string` Payout amount formatted with currency symbol. **source\_currency** `string` Source currency if conversion was applied. **source\_amount** `string` Source amount if conversion was applied. **invoice** `string` Invoice identifier. **description** `string` Payout description. **authentication\_code** `string` Authentication code for the transaction. **rejection\_description** `string` Description if the payout was rejected. **notification\_url** `string` Webhook notification URL. **status** `object` Payout status. **Status** **id** `integer` Status ID. **name** `string` Status name (e.g., "Awaiting"). **beneficiary** `object` Beneficiary information. **Beneficiary** **name** `string` Beneficiary name. **document** `object` Document information. **birthdate** `string` Birthdate. **phone** `string` Phone number. **address** `object` Address information. **receipt\_message** `string` Receipt message. **pix** `object` PIX payment details. Bank account fields (`bank_branch`, `account`, `account_digit`, `account_type`) are returned masked unless your user has permission to read beneficiary data. **PIX** **pix\_key** `string` PIX key used (if applicable). **bank\_code** `string` Bank code. **bank\_branch** `string` Bank branch. **bank\_branch\_digit** `string` Bank branch digit. **account** `string` Account number. **account\_digit** `string` Account digit. **account\_type** `string` Account type. **purpose** `string` Transaction purpose code. **paid\_at** `string` Payment completion timestamp. **created\_at** `string` Creation timestamp. **updated\_at** `string` Last update timestamp. ## Request Examples ### PIX Key Payment Use this method when you have the beneficiary's PIX key. ```bash cURL - PIX Key theme={null} curl --location 'https://api.sandbox.wepayout.com.br/v2/payout/payments' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_TOKEN' \ --data '{ "payment_method": "PIX", "currency": "BRL", "country": "BR", "amount": 43.34, "invoice": "c071bcc5-0c1c-450b-a47f-15fc5321fbe3", "beneficiary": { "name": "João Silva", "document": { "type": "CPF", "number": "82608288200" } }, "pix": { "pix_key": "82608288200" } }' ``` ```javascript JavaScript - PIX Key theme={null} const response = await fetch( 'https://api.sandbox.wepayout.com.br/v2/payout/payments', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN' }, body: JSON.stringify({ payment_method: 'PIX', currency: 'BRL', country: 'BR', amount: 43.34, invoice: 'c071bcc5-0c1c-450b-a47f-15fc5321fbe3', beneficiary: { name: 'João Silva', document: { type: 'CPF', number: '82608288200' } }, pix: { pix_key: '82608288200' } }) } ); const payout = await response.json(); console.log('Payout created:', payout); ``` ```python Python - PIX Key theme={null} import requests url = 'https://api.sandbox.wepayout.com.br/v2/payout/payments' headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN' } payload = { 'payment_method': 'PIX', 'currency': 'BRL', 'country': 'BR', 'amount': 43.34, 'invoice': 'c071bcc5-0c1c-450b-a47f-15fc5321fbe3', 'beneficiary': { 'name': 'João Silva', 'document': { 'type': 'CPF', 'number': '82608288200' } }, 'pix': { 'pix_key': '82608288200' } } response = requests.post(url, headers=headers, json=payload) payout = response.json() print('Payout created:', payout) ``` ### Bank Account Payment Use this method when you have the beneficiary's bank account details. ```bash cURL - Bank Account theme={null} curl --location 'https://api.sandbox.wepayout.com.br/v2/payout/payments' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_TOKEN' \ --data '{ "payment_method": "PIX", "currency": "BRL", "country": "BR", "amount": 50.34, "invoice": "e3317882-f821-455b-b082-dc3ba36e8a57", "beneficiary": { "name": "Maria Santos", "document": { "type": "CPF", "number": "58713371126" } }, "pix": { "ispb": "18236120", "bank_branch": "0496", "account": "51659", "account_digit": "7", "account_type": "CHECKING" } }' ``` ```javascript JavaScript - Bank Account theme={null} const response = await fetch( 'https://api.sandbox.wepayout.com.br/v2/payout/payments', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN' }, body: JSON.stringify({ payment_method: 'PIX', currency: 'BRL', country: 'BR', amount: 50.34, invoice: 'e3317882-f821-455b-b082-dc3ba36e8a57', beneficiary: { name: 'Maria Santos', document: { type: 'CPF', number: '58713371126' } }, pix: { ispb: '18236120', bank_branch: '0496', account: '51659', account_digit: '7', account_type: 'CHECKING' } }) } ); const payout = await response.json(); console.log('Payout created:', payout); ``` ```python Python - Bank Account theme={null} import requests url = 'https://api.sandbox.wepayout.com.br/v2/payout/payments' headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_TOKEN' } payload = { 'payment_method': 'PIX', 'currency': 'BRL', 'country': 'BR', 'amount': 50.34, 'invoice': 'e3317882-f821-455b-b082-dc3ba36e8a57', 'beneficiary': { 'name': 'Maria Santos', 'document': { 'type': 'CPF', 'number': '58713371126' } }, 'pix': { 'ispb': '18236120', 'bank_branch': '0496', 'account': '51659', 'account_digit': '7', 'account_type': 'CHECKING' } } response = requests.post(url, headers=headers, json=payload) payout = response.json() print('Payout created:', payout) ``` ```json 201 Created - PIX Key theme={null} { "id": 124118, "merchant": { "id": 477, "name": "Merchant Name" }, "payment_method": "PIX", "country": "BR", "currency": "BRL", "amount": "R$43.34", "source_currency": null, "source_amount": null, "invoice": "6cc85ff5-7a35-45cb-a8fd-22b9bbe27896", "description": null, "authentication_code": null, "rejection_description": "", "notification_url": null, "status": { "id": 7, "name": "Awaiting" }, "beneficiary": { "name": "João Silva", "document": { "type": "CPF", "number": "82608288200" }, "birthdate": null, "phone": null, "address": { "address": null, "city": null, "country": null, "state_code": null, "zip_code": null } }, "receipt_message": "", "pix": { "pix_key": "82608288200", "bank_code": "", "bank_branch": null, "bank_branch_digit": null, "account": null, "account_digit": null, "account_type": "" }, "purpose": "20", "paid_at": null, "created_at": "2025-11-21T14:59:59.000000Z", "updated_at": "2025-11-21T14:59:59.000000Z" } ``` ```json 201 Created - Bank Account theme={null} { "id": 124117, "merchant": { "id": 477, "name": "Merchant Name" }, "payment_method": "PIX", "country": "BR", "currency": "BRL", "amount": "R$50.34", "source_currency": null, "source_amount": null, "invoice": "27eb1281-e19f-4284-b4b5-b8f598be6148", "description": null, "authentication_code": null, "rejection_description": "", "notification_url": null, "status": { "id": 7, "name": "Awaiting" }, "beneficiary": { "name": "Maria Santos", "document": { "type": "CPF", "number": "58713371126" }, "birthdate": null, "phone": null, "address": { "address": null, "city": null, "country": null, "state_code": null, "zip_code": null } }, "receipt_message": "", "pix": { "pix_key": null, "bank_code": "260", "bank_branch": "0**6", "bank_branch_digit": null, "account": "5***9", "account_digit": "*", "account_type": "********" }, "purpose": "20", "paid_at": null, "created_at": "2025-11-21T14:59:24.000000Z", "updated_at": "2025-11-21T14:59:24.000000Z" } ``` ```json 400 Bad Request theme={null} { "message": "Insufficient balance" } ``` ## Related Resources > [card] [Payout Webhook](/cash-out/payout-webhook) > > Receive real-time payout status notifications > [card] [Get Balance](/api-reference/account/get-balance) > > Check your wallet balance before creating payouts # Create Transfer Source: https://docs.wepayout.co/api-reference/cash-out/payout/create-transfer POST /v2/payout/transfers Create a new payout transfer to an external beneficiary via PIX ## Request Body **merchant\_id** `integer` Merchant ID of the account creating the payout. Required when there is more than one account under your umbrella (sellers). Example: `123` **amount** `number` *required* The payout amount in decimal format. Example: `150.75` **invoice** `string` *required* Unique invoice identifier for this transfer. Example: `PEDIDO-12345` **beneficiary** `object` *required* Beneficiary information. **Beneficiary Object** **name** `string` *required* Beneficiary's full name. Max length: `100` characters **document** `object` *required* Beneficiary's document. **Document Object** **type** `string` *required* Document type. Allowed values: `CPF`, `CNPJ` **number** `string` *required* Document number (digits only). **notification\_url** `string` URL where webhook notifications will be sent. Max length: `255` characters Example: `https://meusite.com/webhook` **pix** `object` *required* PIX payment information. Use either `pix_key` OR bank account details. **PIX Object** **pix\_key** `string` PIX key (CPF, CNPJ, email, phone, or random key). Use this for payments via PIX key. Send the key without masks. Phone keys must be a Brazilian mobile number with exactly 14 characters (`+55` + area code + `9` + 8 digits, e.g. `+5551966084315`), and e-mail keys can have up to 77 characters. See [Accepted PIX key formats](/cash-out/about-payments#accepted-pix-key-formats). **Note**: When using `pix_key`, bank account fields are not required. **ispb** `string` Bank ISPB code. Required when using bank account details. **bank\_branch** `string` Bank branch number. Required when using bank account details. **bank\_branch\_digit** `string` Bank branch digit. Required when using bank account details. **account** `string` Bank account number. Required when using bank account details. **account\_digit** `string` Bank account digit. Required when using bank account details. **account\_type** `string` Account type. Required when using bank account details. Allowed values: `CHECKING`, `SAVINGS` ## Request Examples ### PIX Key ```bash cURL - PIX Key theme={null} curl --request POST \ --url https://api.sandbox.wepayout.com.br/v2/payout/transfers \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "merchant_id": 123, "amount": 150.75, "invoice": "PEDIDO-12345", "beneficiary": { "name": "João da Silva", "document": { "type": "CPF", "number": "12345678901" } }, "notification_url": "https://meusite.com/webhook", "pix": { "pix_key": "joao@email.com" } }' ``` ### Bank Account Details ```bash cURL - Bank Account theme={null} curl --request POST \ --url https://api.sandbox.wepayout.com.br/v2/payout/transfers \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "merchant_id": 123, "amount": 2500.00, "invoice": "FATURA-98765", "beneficiary": { "name": "Maria Oliveira", "document": { "type": "CPF", "number": "98765432100" } }, "notification_url": "https://meusite.com/webhook", "pix": { "ispb": "00000000", "bank_branch": "1234", "bank_branch_digit": "1", "account": "987654", "account_digit": "0", "account_type": "CHECKING" } }' ``` ```json 201 Created theme={null} { "id": 98765, "source_wallet_id": "wallet-uuid-source", "destination_wallet_id": "wallet-uuid-destination", "amount": 10000, "currency": "BRL", "description": "Transfer between accounts", "status": { "id": 1, "name": "Completed" }, "external_id": "TRANSFER-001", "created_at": "2024-06-13T11:00:00.000000Z", "updated_at": "2024-06-13T11:00:00.000000Z" } ``` ```json 400 Bad Request theme={null} { "message": "Insufficient balance" } ``` ## Related Resources > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Create an external payout payment > [card] [Get Balance](/api-reference/account/get-balance) > > Check your wallet balance before creating transfers # Decode QR Code Source: https://docs.wepayout.co/api-reference/cash-out/payout/decode-qr-code POST /v2/payout/qrcode-decode Decode third-parties PIX QR codes to make them payable at the create payment endpoint # Decode QR Code Decode third-parties PIX QR codes to make them payable at the create payment endpoint. ## Request Body **emv** `string` *required* EMV from the QR Code. Example: `00020126580014BR.GOV.BCB.PIX...` **city\_code** `string` City code. **dpp** `string` Expected payment date - optional parameter, should be used with QR Codes that have discount or fines. Format: `YYYY-MM-DD` ## Response **end\_to\_end\_id** `string` End to end ID - send it in `qrcode.end_to_end_id` at the create payment endpoint. It expires 5 minutes after the decode and can be used for a single payment. **credit\_party** `object` Beneficiary data. **Credit Party** **name** `string` PIX name of the beneficiary. **key\_type** `string` PIX key type of the beneficiary. **key** `string` PIX key of the beneficiary. **amount** `number` Amount of the QR code. **is\_amount\_changeable** `boolean` If true, the amount can be changed at payment endpoint. If false, the payment `amount` must be equal to the QR code `amount`. ## Request Example ```bash cURL theme={null} curl --request POST \ --url https://api.sandbox.wepayout.com.br/v2/payout/qrcode-decode \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' \ --header 'Content-Type: application/json' \ --data '{ "emv": "00020126580014BR.GOV.BCB.PIX0136123e4567-e12b-12d1-a456-426655440000520400005303986540510.005802BR5913FULANO DE TAL6008BRASILIA62070503***63041D3D", "dpp": "2023-08-24", "city_code": "string" }' ``` ```javascript JavaScript theme={null} async function decodeQRCode(emv, dpp = null, cityCode = null) { const body = { emv }; if (dpp) body.dpp = dpp; if (cityCode) body.city_code = cityCode; const response = await fetch( 'https://api.sandbox.wepayout.com.br/v2/payout/qrcode-decode', { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer 123', 'Content-Type': 'application/json' }, body: JSON.stringify(body) } ); return await response.json(); } // Usage const qrData = await decodeQRCode( '00020126580014BR.GOV.BCB.PIX0136123e4567-e12b-12d1-a456-426655440000520400005303986540510.005802BR5913FULANO DE TAL6008BRASILIA62070503***63041D3D' ); console.log('QR Code decoded:', qrData); console.log('Beneficiary:', qrData.credit_party.name); console.log('Amount:', qrData.amount); console.log('Can change amount:', qrData.is_amount_changeable); ``` ```python Python theme={null} import requests def decode_qr_code(emv, dpp=None, city_code=None): url = 'https://api.sandbox.wepayout.com.br/v2/payout/qrcode-decode' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer 123', 'Content-Type': 'application/json' } data = {'emv': emv} if dpp: data['dpp'] = dpp if city_code: data['city_code'] = city_code response = requests.post(url, headers=headers, json=data) return response.json() # Usage qr_data = decode_qr_code( '00020126580014BR.GOV.BCB.PIX0136123e4567-e12b-12d1-a456-426655440000520400005303986540510.005802BR5913FULANO DE TAL6008BRASILIA62070503***63041D3D' ) print(f"QR Code decoded: {qr_data}") print(f"Beneficiary: {qr_data['credit_party']['name']}") print(f"Amount: {qr_data['amount']}") print(f"Can change amount: {qr_data['is_amount_changeable']}") ``` ```json 200 OK theme={null} { "end_to_end_id": "string", "credit_party": { "name": "string", "key_type": "string", "key": "string" }, "amount": 0, "is_amount_changeable": true } ``` ```json 400 Invalid or expired theme={null} { "message": "QR Code is invalid or expired" } ``` ```json 400 Invalid status theme={null} { "message": "QR Code doesn't have a valid status" } ``` ```json 422 Unprocessable Entity theme={null} { "message": "The given data was invalid.", "errors": { "emv": ["The emv field is required."] } } ``` ```json 500 Internal Server Error theme={null} { "message": "Internal error" } ``` ## Use Cases > [accordion] Pay Third-Party PIX QR Code > > Decode and pay a PIX QR Code from another institution: > > ```javascript theme={null} > async function payThirdPartyQRCode(qrCodeEmv) { > // Step 1: Decode the QR Code > const qrData = await decodeQRCode(qrCodeEmv); > > console.log(`Paying to: ${qrData.credit_party.name}`); > console.log(`Amount: R$ ${qrData.amount}`); > > // Step 2: Create payment within 5 minutes using the decoded end_to_end_id > const payment = await createPayment({ > payment_method: 'QRCODE', > amount: qrData.amount, // Decimal format, must match when is_amount_changeable is false > currency: 'BRL', > country: 'BR', > invoice: crypto.randomUUID(), > description: `Payment to ${qrData.credit_party.name}`, > qrcode: { > end_to_end_id: qrData.end_to_end_id > } > }); > > return payment; > } > ``` > [accordion] Validate QR Code Before Payment > > Validate QR Code and show details to user before confirming: > > ```javascript theme={null} > async function validateAndShowQRCode(qrCodeEmv) { > try { > const qrData = await decodeQRCode(qrCodeEmv); > > // Show details to user for confirmation > const confirmation = { > beneficiary: qrData.credit_party.name, > pixKey: qrData.credit_party.key, > keyType: qrData.credit_party.key_type, > amount: qrData.amount, > canChangeAmount: qrData.is_amount_changeable, > valid: true > }; > > return confirmation; > } catch (error) { > return { > valid: false, > error: 'Invalid QR Code' > }; > } > } > > // Usage > const validation = await validateAndShowQRCode(qrCodeEmv); > > if (validation.valid) { > console.log('QR Code is valid'); > console.log(`Pay R$ ${validation.amount} to ${validation.beneficiary}`); > > // Show confirmation dialog to user > const confirmed = await showConfirmationDialog(validation); > > if (confirmed) { > await payThirdPartyQRCode(qrCodeEmv); > } > } else { > console.error('Invalid QR Code'); > } > ``` > [accordion] Handle Dynamic Amount QR Codes > > Handle QR Codes where amount can be changed: > > ```javascript theme={null} > async function payDynamicAmountQRCode(qrCodeEmv, customAmount = null) { > const qrData = await decodeQRCode(qrCodeEmv); > > let finalAmount = qrData.amount; > > if (qrData.is_amount_changeable && customAmount) { > finalAmount = customAmount; > console.log(`Amount changed from R$ ${qrData.amount} to R$ ${customAmount}`); > } else if (!qrData.is_amount_changeable && customAmount) { > console.warn('Cannot change amount for this QR Code'); > } > > const payment = await createPayment({ > payment_method: 'QRCODE', > amount: finalAmount, > currency: 'BRL', > country: 'BR', > invoice: crypto.randomUUID(), > description: `Payment to ${qrData.credit_party.name}`, > qrcode: { > end_to_end_id: qrData.end_to_end_id > } > }); > > return payment; > } > ``` > [accordion] Bulk QR Code Processing > > Process multiple QR Codes in batch: > > ```javascript theme={null} > async function processBulkQRCodes(qrCodes) { > const results = []; > > for (const qr of qrCodes) { > try { > const qrData = await decodeQRCode(qr.emv); > > results.push({ > id: qr.id, > success: true, > beneficiary: qrData.credit_party.name, > amount: qrData.amount, > data: qrData > }); > } catch (error) { > results.push({ > id: qr.id, > success: false, > error: error.message > }); > } > } > > return results; > } > > // Usage > const qrCodes = [ > { id: 'QR1', emv: 'emv-string-1' }, > { id: 'QR2', emv: 'emv-string-2' } > ]; > > const results = await processBulkQRCodes(qrCodes); > console.log('Processed QR Codes:', results); > ``` ## Best Practices > [!WARNING] > > **End-to-End ID Validity**: The `end_to_end_id` expires 5 minutes after the decode and can be used for a single payment. Do not store it to pay later: decode the QR Code again right before each payment. An expired or already used `end_to_end_id` returns `404` with the message `End to End ID not found` at the create payment endpoint. > [!WARNING] > > **Amount Validation**: Always check `is_amount_changeable` before allowing users to modify the payment amount. When it is `false`, a payment with a different `amount` is rejected with `400`. > [!NOTE] > > **QR Code Status**: Dynamic QR Codes are accepted only while the charge is active. Any other status returns `400` with the message `QR Code doesn't have a valid status`. > [!TIP] > > **Error Handling**: Implement proper error handling for invalid QR Codes. Not all QR Codes are valid PIX codes. > [!NOTE] > > **QR Code Format**: The EMV string should be the complete PIX QR Code string starting with "00020126...". ## PIX Key Types Common PIX key types you might encounter: | Key Type | Description | Example | | - | - | - | | CPF | Individual tax ID | 12345678900 | | CNPJ | Company tax ID | 12345678000190 | | EMAIL | Email address | [user@example.com](mailto:user@example.com) | | PHONE | Phone number | +5511999999999 | | EVP | Random key | 123e4567-e89b-12d3-a456-426614174000 | ## Integration Flow ```mermaid theme={null} graph TD A[User scans QR Code] --> B[Get EMV string] B --> C[Call Decode QR Code API] C --> D{Valid QR Code?} D -->|Yes| E[Show payment details] D -->|No| F[Show error message] E --> G[User confirms] G --> H[Create Payment] H --> I[Payment processed] ``` ## Related Resources > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Create payment after decoding QR Code > [card] [Callback Payment](/api-reference/cash-out/payout/callback-payment) > > Receive payment notifications # Get Unique Payment Source: https://docs.wepayout.co/api-reference/cash-out/payout/get-unique-payment GET /v2/payout/payments/{id} Get details of a specific payout payment by ID # Get Unique Payment Get details of a specific payout payment by ID. ## Path Parameters **id** `integer` *required* The ID of the payout payment to retrieve. Example: `54321` ## Response Returns a single payout payment object with all details. **id** `integer` WEpayment's auto generated payout ID. **merchant\_id** `integer` Merchant ID that created the payout. **amount** `integer` Payout amount in cents. **currency** `string` Currency code. **country** `string` Country code. **description** `string` Payout description. **recipient** `object` Recipient information. **Recipient** **name** `string` Recipient's full name. **email** `string` Recipient's email address. **document** `object` Recipient's document. **Document** **type** `string` Document type (CPF, CNPJ). **number** `string` Document number. **bank\_account** `object` Recipient's bank account information. **Bank Account** **bank\_code** `string` Bank code (ISPB or COMPE code). **branch** `string` Bank branch number. **account** `string` Bank account number. **account\_digit** `string` Bank account digit. **account\_type** `string` Account type (checking, savings). **status** `object` Payout status. **Status** **id** `integer` Status ID. **name** `string` Status name. **external\_id** `string` Your internal reference ID. **notification\_url** `string` Webhook notification URL. **created\_at** `string` Creation timestamp. **updated\_at** `string` Last update timestamp. ## Request Example ```bash cURL theme={null} curl --request GET \ --url https://api.sandbox.wepayout.com.br/v2/payout/payments/54321 \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` ```javascript JavaScript theme={null} async function getPayment(paymentId) { const response = await fetch( `https://api.sandbox.wepayout.com.br/v2/payout/payments/${paymentId}`, { method: 'GET', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer 123' } } ); return await response.json(); } // Usage const payment = await getPayment(12345); console.log('Payment details:', payment); console.log('Status:', payment.status.name); console.log('Amount:', payment.amount / 100); console.log('Recipient:', payment.recipient.name); ``` ```python Python theme={null} import requests def get_payment(payment_id): url = f'https://api.sandbox.wepayout.com.br/v2/payout/payments/{payment_id}' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer 123' } response = requests.get(url, headers=headers) return response.json() # Usage payment = get_payment(54321) print(f"Payment details: {payment}") print(f"Status: {payment['status']['name']}") print(f"Amount: R$ {payment['amount'] / 100}") print(f"Recipient: {payment['recipient']['name']}") ``` ```json 200 OK theme={null} { "id": 54321, "merchant_id": 1234, "amount": 10000, "currency": "BRL", "country": "BR", "description": "Payment for services rendered", "recipient": { "name": "João Silva", "email": "joao@example.com", "document": { "type": "CPF", "number": "12345678900" }, "bank_account": { "bank_code": "001", "branch": "1234", "account": "12345678", "account_digit": "9", "account_type": "checking" } }, "status": { "id": 3, "name": "Paid" }, "external_id": "ORDER-12345", "notification_url": "https://your-domain.com/webhook/payout", "created_at": "2024-06-13T10:00:00.000000Z", "updated_at": "2024-06-13T10:05:00.000000Z" } ``` ```json 404 Not Found theme={null} { "message": "Payment not found" } ``` ## Use Cases > [accordion] Check Payment Status > > Monitor the status of a specific payout: > > ```javascript theme={null} > async function checkPaymentStatus(paymentId) { > const payment = await getPayment(paymentId); > > console.log(`Payment ${paymentId}:`); > console.log(`Status: ${payment.status.name}`); > console.log(`Amount: R$ ${payment.amount / 100}`); > console.log(`Recipient: ${payment.recipient.name}`); > > return payment.status.id === 3; // 3 = Paid > } > ``` > [accordion] Verify Payment Completion > > Check if a payout has been completed: > > ```javascript theme={null} > async function verifyPaymentCompletion(paymentId) { > const payment = await getPayment(paymentId); > > const isPaid = payment.status.id === 3; > const isFailed = payment.status.id === 4; > const isRejected = payment.status.id === 5; > > if (isPaid) { > console.log('Payment completed successfully'); > return true; > } > > if (isFailed || isRejected) { > console.log(`Payment failed: ${payment.status.name}`); > return false; > } > > console.log('Payment still processing'); > return null; > } > ``` > [accordion] Get Payment Details for Reconciliation > > Retrieve payment details for accounting reconciliation: > > ```javascript theme={null} > async function getPaymentForReconciliation(paymentId) { > const payment = await getPayment(paymentId); > > return { > paymentId: payment.id, > externalId: payment.external_id, > amount: payment.amount / 100, > status: payment.status.name, > recipient: { > name: payment.recipient.name, > document: payment.recipient.document.number, > bank: payment.recipient.bank_account.bank_code, > account: `${payment.recipient.bank_account.branch}-${payment.recipient.bank_account.account}-${payment.recipient.bank_account.account_digit}` > }, > createdAt: payment.created_at, > completedAt: payment.updated_at > }; > } > > // Usage > const reconciliation = await getPaymentForReconciliation(54321); > console.log('Reconciliation data:', reconciliation); > ``` > [accordion] Track Payment by External ID > > Find and track a payment using your internal reference: > > ```javascript theme={null} > async function trackPaymentByExternalId(externalId) { > // First, list payments filtered by external_id > const listResponse = await fetch( > `https://api.sandbox.wepayout.com.br/v2/payout/payments?external_id=${externalId}`, > { > headers: { > 'Authorization': 'Bearer 123', > 'Accept': 'application/json' > } > } > ); > > const list = await listResponse.json(); > > if (list.data.length === 0) { > throw new Error('Payment not found'); > } > > // Get full details > const paymentId = list.data[0].id; > return await getPayment(paymentId); > } > > // Usage > const payment = await trackPaymentByExternalId('ORDER-12345'); > console.log('Payment status:', payment.status.name); > ``` > [accordion] Monitor Multiple Payments > > Check status of multiple payouts: > > ```javascript theme={null} > async function monitorPayments(paymentIds) { > const results = []; > > for (const paymentId of paymentIds) { > try { > const payment = await getPayment(paymentId); > results.push({ > id: paymentId, > status: payment.status.name, > amount: payment.amount, > completed: payment.status.id === 3 > }); > } catch (error) { > results.push({ > id: paymentId, > error: error.message > }); > } > } > > return results; > } > > // Usage > const paymentIds = [54321, 54322, 54323]; > const statuses = await monitorPayments(paymentIds); > console.log('Payment statuses:', statuses); > ``` ## Status Codes | Status ID | Status Name | Description | | - | - | - | | 1 | Created | Payout has been created | | 2 | Processing | Payout is being processed | | 3 | Paid | Payout has been paid successfully | | 4 | Failed | Payout failed | | 5 | Rejected | Payout rejected by compliance | | 6 | Cancelled | Payout was cancelled | ## Best Practices > [!NOTE] > > **Status Monitoring**: Use webhooks instead of polling this endpoint repeatedly to check payment status. > [!TIP] > > **External ID**: Use the external\_id to track payments in your system and correlate with your internal records. > [!WARNING] > > **Error Handling**: Always implement proper error handling for 404 responses when the payment ID doesn't exist. ## Related Resources > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Create a new payout payment > [card] [List Payments](/api-reference/cash-out/payout/list-payment) > > List all payout payments > [card] [Callback Payment](/api-reference/cash-out/payout/callback-payment) > > Receive payment status updates > [card] [Get Balance](/api-reference/account/get-balance) > > Check your wallet balance > [card] [Get Statement](/api-reference/account/get-statement) > > View account statement # List Payment Source: https://docs.wepayout.co/api-reference/cash-out/payout/list-payment GET /v2/payout/payments List all payout payments with optional filters # List Payment List all payout payments with optional filters. ## Query Parameters **merchant\_id** `integer` Filter by merchant ID. Min: `2`, Max: `10000` **external\_id** `string` Filter by your internal reference ID. Max length: `255` characters **status\_id** `integer` Filter by status ID. **created\_at\_start** `string` Filter payments created after this date. Format: `YYYY-MM-DD` **created\_at\_end** `string` Filter payments created before this date. Format: `YYYY-MM-DD` **updated\_at\_start** `string` Filter payments updated after this date. Format: `YYYY-MM-DD` **updated\_at\_end** `string` Filter payments updated before this date. Format: `YYYY-MM-DD` **page** `integer` Page number for pagination. Default: `1` **per\_page** `integer` Number of items per page. Default: `15`, Max: `100` **sort\_by** `string` Field to sort by. Allowed values: `id`, `created_at`, `updated_at`, `amount` Default: `id` **sort\_order** `string` Sort order. Allowed values: `asc`, `desc` Default: `desc` ## Response Returns an array of payout payment objects with pagination metadata. **data** `array` Array of payout payment objects. **Payment Object** **id** `integer` WEpayment's auto generated payout ID. **merchant\_id** `integer` Merchant ID that created the payout. **amount** `integer` Payout amount in cents. **currency** `string` Currency code. **country** `string` Country code. **description** `string` Payout description. **recipient** `object` Recipient information. **status** `object` Payout status. **external\_id** `string` Your internal reference ID. **notification\_url** `string` Webhook notification URL. **created\_at** `string` Creation timestamp. **updated\_at** `string` Last update timestamp. **meta** `object` Pagination metadata. **Pagination** **current\_page** `integer` Current page number. **from** `integer` First item number on current page. **last\_page** `integer` Last page number. **per\_page** `integer` Items per page. **to** `integer` Last item number on current page. **total** `integer` Total number of items. **links** `object` Pagination links. **Links** **first** `string` URL to first page. **last** `string` URL to last page. **prev** `string` URL to previous page (null if on first page). **next** `string` URL to next page (null if on last page). ## Request Example ```bash cURL - All Payments theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v2/payout/payments?page=1&per_page=15' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` ```bash cURL - Filter by External ID theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v2/payout/payments?external_id=ORDER-12345' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` ```bash cURL - Filter by Status theme={null} curl --request GET \ --url '"https://api.sandbox.wepayout.com.br/v2/payout/payments?status_id=3"' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` ```bash cURL - Filter by Date Range theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v2/payout/payments?created_at_start=2024-01-01&created_at_end=2024-12-31' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` ```javascript JavaScript theme={null} async function listPayouts(filters = {}) { const params = new URLSearchParams({ page: filters.page || 1, per_page: filters.perPage || 15, ...filters }); const response = await fetch( `https://api.sandbox.wepayout.com.br/v2/payout/payments?${params}`, { method: 'GET', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer 123' } } ); return await response.json(); } // Usage examples // List all payouts const allPayouts = await listPayouts(); // Filter by status const paidPayouts = await listPayouts({ status_id: 3 }); // Filter by external ID const orderPayout = await listPayouts({ external_id: 'ORDER-12345' }); // Filter by date range const monthPayouts = await listPayouts({ created_at_start: '2024-01-01', created_at_end: '2024-01-31' }); console.log(`Total payouts: ${allPayouts.meta.total}`); console.log(`Current page: ${allPayouts.meta.current_page} of ${allPayouts.meta.last_page}`); ``` ```python Python theme={null} import requests def list_payouts(filters=None): url = 'https://api.sandbox.wepayout.com.br/v2/payout/payments' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer 123' } params = { 'page': 1, 'per_page': 15 } if filters: params.update(filters) response = requests.get(url, headers=headers, params=params) return response.json() # Usage examples # List all payouts all_payouts = list_payouts() # Filter by status paid_payouts = list_payouts({'status_id': 3}) # Filter by external ID order_payout = list_payouts({'external_id': 'ORDER-12345'}) # Filter by date range month_payouts = list_payouts({ 'created_at_start': '2024-01-01', 'created_at_end': '2024-01-31' }) print(f"Total payouts: {all_payouts['meta']['total']}") print(f"Current page: {all_payouts['meta']['current_page']} of {all_payouts['meta']['last_page']}") ``` ```json 200 OK theme={null} { "data": [ { "id": 54321, "merchant_id": 1234, "amount": 10000, "currency": "BRL", "country": "BR", "description": "Payment for services rendered", "recipient": { "name": "João Silva", "email": "joao@example.com", "document": { "type": "CPF", "number": "12345678900" }, "bank_account": { "bank_code": "001", "branch": "1234", "account": "12345678", "account_digit": "9", "account_type": "checking" } }, "status": { "id": 3, "name": "Paid" }, "external_id": "ORDER-12345", "notification_url": "https://your-domain.com/webhook/payout", "created_at": "2024-06-13T10:00:00.000000Z", "updated_at": "2024-06-13T10:05:00.000000Z" } ], "meta": { "current_page": 1, "from": 1, "last_page": 5, "per_page": 15, "to": 15, "total": 73 }, "links": { "first": "https://api.sandbox.wepayout.com.br/v2/payout/payments?page=1", "last": "https://api.sandbox.wepayout.com.br/v2/payout/payments?page=5", "prev": null, "next": "https://api.sandbox.wepayout.com.br/v2/payout/payments?page=2" } } ``` ## Use Cases > [accordion] List All Payouts > > Retrieve all payouts with pagination: > > ```javascript theme={null} > async function getAllPayouts(page = 1, perPage = 15) { > const response = await listPayouts({ page, perPage }); > return response; > } > ``` > [accordion] Filter by Status > > Get payouts by specific status: > > ```javascript theme={null} > async function getPayoutsByStatus(statusId) { > const response = await listPayouts({ status_id: statusId }); > return response.data; > } > > // Get paid payouts (status_id = 3) > const paidPayouts = await getPayoutsByStatus(3); > ``` > [accordion] Search by External ID > > Find a specific payout by your internal reference: > > ```javascript theme={null} > async function findPayoutByExternalId(externalId) { > const response = await listPayouts({ external_id: externalId }); > return response.data[0]; // Return first match > } > ``` > [accordion] Date Range Report > > Generate a report for a specific date range: > > ```javascript theme={null} > async function getPayoutsReport(startDate, endDate) { > const response = await listPayouts({ > created_at_start: startDate, > created_at_end: endDate, > per_page: 100, > sort_by: 'created_at', > sort_order: 'asc' > }); > > return response; > } > > // Get payouts from January 2024 > const report = await getPayoutsReport('2024-01-01', '2024-01-31'); > ``` > [accordion] Pagination Handler > > Handle pagination to retrieve all payouts: > > ```javascript theme={null} > async function getAllPayoutsWithPagination() { > let allPayouts = []; > let currentPage = 1; > let hasMorePages = true; > > while (hasMorePages) { > const response = await listPayouts({ > page: currentPage, > per_page: 100 > }); > > allPayouts = allPayouts.concat(response.data); > > hasMorePages = response.meta.current_page < response.meta.last_page; > currentPage++; > } > > return allPayouts; > } > ``` ## Status IDs Common payout status IDs for filtering: | ID | Status Name | Description | | - | - | - | | 1 | Created | Payout has been created | | 2 | Processing | Payout is being processed | | 3 | Paid | Payout has been paid successfully | | 4 | Failed | Payout failed | | 5 | Rejected | Payout rejected by compliance | | 6 | Cancelled | Payout was cancelled | ## Best Practices > [!NOTE] > > **Pagination**: Always use pagination when listing payouts to avoid performance issues. The default page size is 15, with a maximum of 100 items per page. > [!WARNING] > > **Date Filters**: When using date range filters, ensure the range is not too large to avoid timeouts. For large date ranges, consider breaking them into smaller chunks. > [!TIP] > > **Caching**: Consider caching the results for frequently accessed pages to reduce API calls and improve performance. ## Related Resources > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Create a new payout payment > [card] [Callback Payment](/api-reference/cash-out/payout/callback-payment) > > Receive payout status updates > [card] [Get Balance](/api-reference/account/get-balance) > > Check your wallet balance > [card] [Get Statement](/api-reference/account/get-statement) > > View account statement # Resend Payout Webhooks (Bulk) Source: https://docs.wepayout.co/api-reference/cash-out/webhooks/resend-bulk POST /v2/payout/notifications/resend Dispatch a bulk job to resend payout webhook notifications for a given merchant and time range ## Overview This endpoint allows you to resend webhook notifications in bulk for payout transactions within a specified time window. It dispatches an asynchronous job and returns a `job_id` that can be used to track progress via the [Job Status](/api-reference/cash-out/webhooks/resend-bulk-status) endpoint. > [!NOTE] > > The time range is limited to a maximum of **3 hours** between `start_time` and `end_time`. > [!WARNING] > > Only one resend job can run at a time per merchant and start time. If a job is already running for the same merchant and start time, the request will return `409 Conflict`. ## Request Body **merchant\_id** `integer` *required* The ID of the merchant whose payout notifications will be resent. Must be one of the merchant IDs associated with your account. **start\_time** `string` *required* Start of the time range for filtering payout transactions. Format: `YYYY-MM-DD HH:MM:SS` Example: `"2026-03-24 08:00:00"` **end\_time** `string` *required* End of the time range for filtering payout transactions. Must be after `start_time`. Maximum range: **3 hours** from `start_time`. Format: `YYYY-MM-DD HH:MM:SS` Example: `"2026-03-24 11:00:00"` **status\_ids** `array` Optional list of status IDs to filter which payout transactions will have notifications resent. If omitted, all notifiable statuses are included. Notifiable status IDs: | ID | Status | | - | - | | 1 | Received | | 3 | Paid | | 4 | Rejected | | 5 | In Review | | 6 | Canceled | | 10 | Expired | | 11 | Invalid Data | Example: `[3, 6]` **dry\_run** `boolean` When `true`, the job is **not dispatched**. Instead, only the count of matching transactions is returned. Useful for estimating volume before triggering the actual resend. Default: `false` ## Response **job\_id** `string` Unique identifier for the dispatched job. Use this to query the job status. Example: `"a3f1bc2e4d8f0a1b2c3d4e5f6a7b8c9d"` **total** `integer` Total number of payout transactions matched and queued for webhook resend. Example: `87` ```json 202 theme={null} { "job_id": "a3f1bc2e4d8f0a1b2c3d4e5f6a7b8c9d", "total": 87 } ``` ```json 200 (dry_run) theme={null} { "total": 87 } ``` ```json 409 theme={null} { "message": "A resend job is already running for this merchant and time range." } ``` ```json 422 theme={null} { "message": "Validation error.", "errors": { "end_time": [ "The time range must not exceed 3 hours." ] } } ``` ## Code Examples ```bash cURL theme={null} curl -X POST "https://api.wepayments.com/v2/payout/notifications/resend" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "merchant_id": 303, "start_time": "2026-03-24 08:00:00", "end_time": "2026-03-24 11:00:00", "status_ids": [3, 6], "dry_run": false }' ``` ```javascript JavaScript theme={null} const response = await fetch('https://api.wepayments.com/v2/payout/notifications/resend', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ merchant_id: 303, start_time: '2026-03-24 08:00:00', end_time: '2026-03-24 11:00:00', status_ids: [3, 6], dry_run: false }) }); const { job_id, total } = await response.json(); console.log(`Job dispatched: ${job_id} (${total} transactions)`); ``` ```python Python theme={null} import requests response = requests.post( 'https://api.wepayments.com/v2/payout/notifications/resend', headers={'Authorization': 'Bearer YOUR_API_KEY'}, json={ 'merchant_id': 303, 'start_time': '2026-03-24 08:00:00', 'end_time': '2026-03-24 11:00:00', 'status_ids': [3, 6], 'dry_run': False } ) data = response.json() print(f"Job dispatched: {data['job_id']} ({data['total']} transactions)") ``` ```php PHP theme={null} 303, 'start_time' => '2026-03-24 08:00:00', 'end_time' => '2026-03-24 11:00:00', 'status_ids' => [3, 6], 'dry_run' => false ])); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = json_decode(curl_exec($ch), true); curl_close($ch); echo "Job dispatched: {$response['job_id']} ({$response['total']} transactions)"; ?> ``` ## Related > [card] [Job Status](/api-reference/cash-out/webhooks/resend-bulk-status) > > Track the progress of a dispatched resend job > [card] [Payout Webhook](/cash-out/payout-webhook) > > Understand the webhook payload structure > [card] [Status Flow](/cash-out/status-flow) > > Understand payout status lifecycle # Resend Job Status Source: https://docs.wepayout.co/api-reference/cash-out/webhooks/resend-bulk-status GET /v2/payout/notifications/resend/{jobId} Check the progress and status of a bulk payout webhook resend job ## Overview After dispatching a bulk resend job via [Resend Payout Webhooks (Bulk)](/api-reference/cash-out/webhooks/resend-bulk), use this endpoint to monitor its progress. Job state is available for **24 hours** after completion. ## Path Parameters **jobId** `string` *required* The job ID returned by the [bulk resend endpoint](/api-reference/cash-out/webhooks/resend-bulk). Example: `"a3f1bc2e4d8f0a1b2c3d4e5f6a7b8c9d"` ## Response **status** `string` Current status of the job. | Value | Description | | - | - | | `processing` | Job is running — transactions are being queued | | `completed` | Job finished successfully | | `failed` | Job encountered a fatal error and was aborted | **merchant\_id** `integer` ID of the merchant for which the resend was triggered. Example: `303` **start\_time** `string` Start of the time range used in the original request. Example: `"2026-03-24 08:00:00"` **end\_time** `string` End of the time range used in the original request. Example: `"2026-03-24 11:00:00"` **total** `integer` Total number of payout transactions matched at the time of dispatch. Example: `87` **queued** `integer` Number of webhook notifications successfully enqueued so far. Example: `60` **failed** `integer` Number of webhook notifications that failed to be enqueued. Example: `1` **started\_at** `string` ISO 8601 timestamp of when the job started. Example: `"2026-03-24T08:05:00+00:00"` **updated\_at** `string` ISO 8601 timestamp of the last state update. Example: `"2026-03-24T08:07:32+00:00"` **reason** `string` Present only when `status` is `failed`. Describes the fatal error that caused the job to abort. Example: `"Connection refused"` ```json 200 (processing) theme={null} { "status": "processing", "merchant_id": 303, "start_time": "2026-03-24 08:00:00", "end_time": "2026-03-24 11:00:00", "total": 87, "queued": 60, "failed": 0, "started_at": "2026-03-24T08:05:00+00:00", "updated_at": "2026-03-24T08:07:32+00:00" } ``` ```json 200 (completed) theme={null} { "status": "completed", "merchant_id": 303, "start_time": "2026-03-24 08:00:00", "end_time": "2026-03-24 11:00:00", "total": 87, "queued": 86, "failed": 1, "started_at": "2026-03-24T08:05:00+00:00", "updated_at": "2026-03-24T08:08:45+00:00" } ``` ```json 200 (failed) theme={null} { "status": "failed", "merchant_id": 303, "start_time": "2026-03-24 08:00:00", "end_time": "2026-03-24 11:00:00", "total": 87, "queued": 0, "failed": 0, "started_at": "2026-03-24T08:05:00+00:00", "updated_at": "2026-03-24T08:05:03+00:00", "reason": "Connection refused" } ``` ```json 404 theme={null} { "message": "Job not found." } ``` ```json 403 theme={null} { "message": "Forbidden" } ``` ## Code Examples ```bash cURL theme={null} curl -X GET "https://api.wepayments.com/v2/payout/notifications/resend/a3f1bc2e4d8f0a1b2c3d4e5f6a7b8c9d" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```javascript JavaScript theme={null} const jobId = 'a3f1bc2e4d8f0a1b2c3d4e5f6a7b8c9d'; const response = await fetch( `https://api.wepayments.com/v2/payout/notifications/resend/${jobId}`, { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ); const job = await response.json(); console.log(`Status: ${job.status} — queued: ${job.queued}/${job.total}`); ``` ```python Python theme={null} import requests job_id = 'a3f1bc2e4d8f0a1b2c3d4e5f6a7b8c9d' response = requests.get( f'https://api.wepayments.com/v2/payout/notifications/resend/{job_id}', headers={'Authorization': 'Bearer YOUR_API_KEY'} ) job = response.json() print(f"Status: {job['status']} — queued: {job['queued']}/{job['total']}") ``` ```php PHP theme={null} ``` ## Polling the Job Job state is updated in real-time as the job processes each chunk of 200 transactions. A simple polling pattern: ```javascript theme={null} async function waitForJob(jobId, intervalMs = 3000) { while (true) { const res = await fetch( `https://api.wepayments.com/v2/payout/notifications/resend/${jobId}`, { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ); const job = await res.json(); console.log(`[${job.status}] queued: ${job.queued}/${job.total}, failed: ${job.failed}`); if (job.status === 'completed' || job.status === 'failed') { return job; } await new Promise(resolve => setTimeout(resolve, intervalMs)); } } ``` > [!NOTE] > > Job state is stored for **24 hours**. After that, the endpoint will return `404`. ## Related > [card] [Resend Webhooks (Bulk)](/api-reference/cash-out/webhooks/resend-bulk) > > Dispatch a new bulk resend job > [card] [Payout Webhook](/cash-out/payout-webhook) > > Understand the webhook payload structure # Create Charge Source: https://docs.wepayout.co/api-reference/credit-card/create-charge POST /v1/payin/payments/credit-card Create a new credit card charge with payment page or transparent checkout ## Request Body **callbackUrl** `string` The url where we will submit the callbacks. Without it we have no endpoint to notify and you have to poll the charge to learn its status — see [Webhooks](/credit-card/webhook). Max: `255` characters **customNumber** `string` *required* Your identification number, it must be unique on our database. **clientId** `integer or null` The use of clientID to create payments. Is mandatory if there is more than one account under the same clientId. **title** `object` *required* Payment instructions. **title properties** **title.expireDate** `string` *required* Expiration date in format `YYYY-MM-DDTHH:SS`. Ex.: 2021-12-31T23:59:59 **title.amountInCents** `integer` *required* Amount in cents (e.g., 8652 = R\$ 86.52) **title.instructions** `string` Payment instructions text **buyer** `object` *required* The person that you are charging object. **buyer properties** **buyer.name** `string` *required* Buyer's full name **buyer.document** `object` *required* **document properties** **buyer.document.number** `string` *required* CPF or CNPJ number **buyer.document.type** `string` *required* Document type: `CPF` or `CNPJ` **buyer.address** `object` *required* **address properties** **buyer.address.street** `string` *required* Street name **buyer.address.number** `string` *required* Street number **buyer.address.complement** `string` Address complement **buyer.address.zipCode** `string` *required* ZIP code **buyer.address.city** `string` *required* City name **buyer.address.district** `string` *required* District/neighborhood **buyer.address.stateCode** `string` *required* State code (2 letters, e.g., "PR") **refundMode** `string` Default: `FULL_REFUND_CLIENT` Enum: `FULL_REFUND_CLIENT`, `FULL_REFUND_RECIPIENT`, `REFUND_BY_SPLIT` Enum of some refund options. **sender** `object` *required* **REQUIRED FOR CREDIT-CARD CHARGES.** Use this object to inform the legal name of the final beneficiary, it could be your company's name or the company you are proving a service for. Final Beneficiary is a person or a company that will receive the amount paid trough the boleto. **sender properties** **sender.name** `string` *required* Sender name **sender.document** `string` *required* Sender document (CPF or CNPJ) **sender.helpdesk** `string` *required* Sender helpdesk contact **checkout** `object` Payer informations for transparent checkout. Use `token` for new card payment or `card_id` for saved card payment. **checkout properties** **checkout.token** `string` Card token generated by the tokenization process. Required if `card_id` is not provided. Max length: 190 characters. **checkout.card\_id** `integer` ID of a previously saved credit card. Required if `token` is not provided. **checkout.installments** `integer` *required* Number of installments (1 for single payment). Required unless checkout is null. **checkout.payment\_method\_id** `string` Payment method identifier (e.g., "master", "visa", "elo"). Max length: 30 characters. Required if `card_id` is not provided. **checkout.payer\_name** `string` *required* Payer's full name. Max length: 100 characters. Required unless checkout is null. **checkout.payer\_phone** `string` Payer's phone number. Must be numeric with 5 to 45 digits. **checkout.payer\_document** `string` Payer's CPF or CNPJ number. Must be a valid tax number. **checkout.payer\_address** `object` **payer\_address properties** **checkout.payer\_address.zip\_code** `string` *required* ZIP code. Max length: 45 characters. Required if payer\_address is provided. **checkout.payer\_address.street\_name** `string` *required* Street name. Max length: 100 characters. Required if payer\_address is provided. **checkout.payer\_address.street\_number** `string` *required* Street number. Max length: 45 characters. Required if payer\_address is provided. **checkout.payer\_email** `string` Payer's email address. Required if `save_card` is set to `1`. **checkout.save\_card** `integer` Flag to save card for future use. `0` = do not save, `1` = save card. Must be 0 or 1. **statement\_descriptor** `string` Short description shown at the credit-card bill. **product\_info** `array of objects` Array with product metadata. **use\_3ds** `integer or null` Default: `null` Enum: `0`, `1`, `null` Flag to inform that the charge must validate through three d secure mode ## Response **id** `string` Charge ID **key** `string` Unique key for payment page access **clientId** `integer` Client ID **clientName** `string` Client name **senderName** `string or null` Sender name **senderHelpdesk** `string or null` Sender helpdesk **buyerName** `string` Buyer name **buyerDocument** `string` Buyer document **buyerEmail** `string` Buyer email **customNumber** `string` Your custom number **ourNumber** `string or null` Our internal number **digitableLine** `string or null` Digitable line (for boleto) **barCodeNumber** `string or null` Bar code number (for boleto) **status** `object` Current status **status properties** **status.id** `integer` Status ID **status.name** `string` Status name **sender** `object` Sender information **typePayin** `string` Type of payment (e.g., "credit-card") **instructions** `string` Payment instructions **amountCents** `integer` Amount in cents **paidAmountCents** `integer or null` Paid amount in cents **paidAt** `string or null` Payment date **expiresAt** `string` Expiration date **createdAt** `string` Creation date **fine** `object or null` Fine information **discount** `object or null` Discount information **statusHistory** `array` Status change history **refundMode** `string` Refund mode **refundAmountCents** `integer` Refunded amount in cents **payinRefunds** `array` Refund records **payin\_substatus** `string or null` Sub-status **kyc** `object or null` KYC information **installments** `array` Installment information **hasAdvancement** `boolean` Has advancement flag **use3ds** `boolean` 3D Secure flag ```json 201 theme={null} { "id": "28018", "key": "e1ebf9d914174902a76a5af436f091d09cca0b1e9ad8984b5dcdfeead67ce6b8", "clientId": 1, "clientName": "Your company", "senderName": null, "senderHelpdesk": null, "buyerName": "Maria da Silva", "buyerDocument": "34960826312", "buyerEmail": "buyer-email@wepayments.com.br", "customNumber": "YOUR-CODE1234", "ourNumber": null, "digitableLine": null, "barCodeNumber": null, "status": { "id": 1, "name": "awaiting approval" }, "sender": { "name": null, "document": null, "helpdesk": null }, "typePayin": "credit-card", "instructions": "Esse Pagamento é referente ao pedido 123 na loja abcd", "amountCents": 8652, "paidAmountCents": null, "paidAt": null, "expiresAt": "2024-12-31 23:59:59", "createdAt": "2024-02-21T19:15:00.000000Z", "fine": null, "discount": null, "statusHistory": [ { "status": { "id": 1, "name": "Created" } }, { "status": { "id": 6, "name": "awaiting approval" }, "id": 48859, "updatedAt": "2024-02-21T19:15:04.000000Z" } ], "refundMode": "FULL_REFUND_CLIENT", "refundAmountCents": 0, "payinRefunds": [], "payin_substatus": null, "kyc": null, "installments": [], "hasAdvancement": true, "use3ds": false } ``` ```json 400 theme={null} { "message": "Bad Resquest message" } ``` ```json 401 theme={null} { "error": "Unauthorized" } ``` ```json 403 theme={null} { "error": "Forbidden resource" } ``` ```json 404 theme={null} { "status": false, "message": "Payin not found", "data": "No result were found for the given parameters. Please try again using other suported keys: id, key, ourNumber or end_to_end" } ``` ```json 422 theme={null} { "status": false, "message": "Validation error", "data": { "title.expireDate": [ "The title.expire date must be a date after now." ], "product_info": [ "The product info field is required." ] } } ``` ```json 500 Internal Server Error theme={null} { "status": false, "message": "Server error" } ``` # Create Data Qualification Source: https://docs.wepayout.co/api-reference/data-qualification/create-data-qualification POST /v1/payout/data-qualification Register a batch of data qualification orders You can use this endpoint to create a data qualification batch. In the data attribute you may pass a list of bank account data to be qualified. You can group your data qualification in batches using the `batch_code` field. ## Request Body **merchant\_id** `integer` The Merchant ID. Required when you have access to more than one Merchant. **service\_id** `integer` *required* The service ID. The available services can be retrieved in the endpoint [GET /v1/payout/data-qualification/services](/api-reference/data-qualification/get-services). Allowed values: `1`, `2`, `3`, `4`, `5` **data** `array` *required* Array of data qualification records. **Data Object** **amount** `number` Amount in local currency, used in services 4 and 5 only. Min: `0.01` Max: `150000` Example: `1000` **custom\_code** `string` *required* Custom code (Invoice) must be unique in our database. Example: `YourCustomCode` **batch\_code** `string` *required* The code used to group data qualification processes. Example: `YOURAPPCODE` **notification\_url** `string` We will send you an HTTP POST with a Notification Object when deposit status changes. Example: `https://your.endpoint.to.update` **beneficiary** `object` *required* Beneficiary information. **Beneficiary Object** **name** `string` *required* Beneficiary's full name. Example: `The Name` **bank\_code** `string` *required* Bank code. Example: `147` **bank\_branch** `string` *required* Bank branch. Example: `0000` **bank\_branch\_digit** `string` Bank branch digit. Example: `1` **account** `string` *required* Account number. Example: `1030000` **account\_digit** `string` *required* Account digit. Example: `1` **account\_type** `string` *required* Account type. Allowed values: `SAVINGS`, `CHECKING` Example: `CHECKING` **document** `string` *required* CPF or CNPJ Number. Example: `12533009091` **document\_type** `string` *required* Document type. Allowed values: `cpf`, `cnpj` Example: `cpf` **birthdate** `string` Beneficiary's birthdate. Format: `YYYY-MM-DD` Example: `1970-01-01` **phone** `string` Phone number with country code. Example: `5541987456321` **city** `string` City name. Example: `Curitiba` **postal\_code** `string` Postal code. Example: `80200-100` **province\_code** `string` State/Province code. Example: `PR` **address** `string` Street address. Example: `Rua a Número 10` ## Webhook Callback When you provide a `notification_url`, we will send HTTP POST requests to your endpoint when the data qualification status changes. > [!NOTE] > > **Webhook Signature**: All data qualification webhooks are signed with an sha256 hash provided in the `Authorization` header. The hash is sent as a Bearer token. eg.: `Bearer {hash}` > > To validate the signature you must concatenate the request body and your APIKey used to create the payments and hash this string using the sha256 algorithm. For example: `{JSON_BODY...}APIKEY` ### Webhook Payload **id** `string` Our ID. Example: `1` **step** `integer` An integer value that indicates the step that the data-qualification process is. * `1` - Processing - Intermediary step * `2` - Valid data - Final step * `3` - Invalid data - Final step **status\_id** `integer` An integer value that indicates the current data-qualification status. * `1` - Received - The data qualification is received and will be processed soon * `5` - Valid data - Final status * `6` - Invalid data - Final status * `7` - No Process - The account can not be validated - Final status **custom\_code** `string` Your Custom Code. Example: `YOURAPPCODE` **batch\_code** `string` The data qualification batch code. Example: `bc101` **message** `string` The description of the data qualification update. **name** `string` Beneficiary name. **document** `string` Beneficiary document. **bank\_code** `string` Bank code. **bank\_branch** `string` Bank branch. **bank\_branch\_digit** `string` Bank branch digit. **account** `string` Account number. **account\_digit** `string` Account digit. **account\_type** `string` Account type: `c` for Checking accounts, `s` for Savings accounts. **pix\_key** `string` PIX key if applicable. ## Response **200** `object` All data qualification records provided have been successfully processed. **400** `object` When some of the records provided in the data list have errors during processing. **Error Object** **message** `string` Error message. **info** `object` This return object is divided in three properties: **Info Object** **errors** `array` Contains the records that have any error during processing. **Error Item** **line** `integer` Represents which record in the batch data has errors. **batch\_code** `string` The batch\_code provided. **custom\_code** `string` The custom\_code provided. **message** `string` Message error description. **uploadSuccess** `array` Contains the records that have been successfully processed. **Success Item** **line** `integer` Represents which record in the batch data was successful. **batch\_code** `string` The batch\_code provided. **custom\_code** `string` The custom\_code provided. **uploadChangeService** `array` The records that have the service changed automatically. **Changed Service Item** **line** `integer` Represents which record in the batch data had service changed. **batch\_code** `string` The batch\_code provided. **custom\_code** `string` The custom\_code provided. **message** `string` The new service assigned to record. ## Request Example ```bash cURL theme={null} curl --request POST \ --url 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' \ --header 'Content-Type: application/json' \ --data '{ "service_id": 2, "data": [ { "custom_code": "DQ001", "batch_code": "BATCH001", "notification_url": "https://your.endpoint.to.update", "beneficiary": { "name": "Maria Jose", "bank_code": "147", "bank_branch": "0000", "bank_branch_digit": "1", "account": "1030000", "account_digit": "1", "account_type": "CHECKING", "document": "12533009091", "document_type": "cpf", "birthdate": "1970-01-01", "phone": "5541987456321", "city": "Curitiba", "postal_code": "80200-100", "province_code": "PR", "address": "Rua a Número 10" } } ] }' ``` ```javascript JavaScript theme={null} async function createDataQualification(data) { const response = await fetch( 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification', { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer {token}', 'Content-Type': 'application/json' }, body: JSON.stringify({ service_id: 2, data: [ { custom_code: 'DQ001', batch_code: 'BATCH001', notification_url: 'https://your.endpoint.to.update', beneficiary: { name: 'Maria Jose', bank_code: '147', bank_branch: '0000', bank_branch_digit: '1', account: '1030000', account_digit: '1', account_type: 'CHECKING', document: '12533009091', document_type: 'cpf', birthdate: '1970-01-01', phone: '5541987456321', city: 'Curitiba', postal_code: '80200-100', province_code: 'PR', address: 'Rua a Número 10' } } ] }) } ); if (!response.ok) { throw new Error(`Failed to create data qualification: ${response.statusText}`); } return await response.json(); } const result = await createDataQualification(); console.log('Data qualification created:', result); ``` ```python Python theme={null} import requests def create_data_qualification(): url = 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer {token}', 'Content-Type': 'application/json' } payload = { 'service_id': 2, 'data': [ { 'custom_code': 'DQ001', 'batch_code': 'BATCH001', 'notification_url': 'https://your.endpoint.to.update', 'beneficiary': { 'name': 'Maria Jose', 'bank_code': '147', 'bank_branch': '0000', 'bank_branch_digit': '1', 'account': '1030000', 'account_digit': '1', 'account_type': 'CHECKING', 'document': '12533009091', 'document_type': 'cpf', 'birthdate': '1970-01-01', 'phone': '5541987456321', 'city': 'Curitiba', 'postal_code': '80200-100', 'province_code': 'PR', 'address': 'Rua a Número 10' } } ] } response = requests.post(url, headers=headers, json=payload) response.raise_for_status() return response.json() result = create_data_qualification() print('Data qualification created:', result) ``` ```json 200 OK theme={null} { "message": "All records processed successfully" } ``` ```json 400 Bad Request theme={null} { "message": "Error message.", "info": { "errors": [ { "line": 1, "batch_code": "bc101", "custom_code": "cc101", "message": "Name format invalid" } ], "uploadSuccess": [ { "line": 2, "batch_code": "bc102", "custom_code": "cc102" } ], "uploadChangeService": [ { "line": 3, "batch_code": "bc103", "custom_code": "cc103", "message": "Data qualification by system" } ] } } ``` # Get Data Qualification By Custom Code Source: https://docs.wepayout.co/api-reference/data-qualification/get-by-custom-code GET /v1/payout/data-qualification/custom-code/{customCode} Find a data qualification order using custom code ## Path Parameters **customCode** `string` *required* The custom code (invoice) used when creating the data qualification. ## Response **id** `integer` Our ID. Example: `123` **batch\_code** `string` Batch code. Example: `abc101` **custom\_code** `string` Your ID in our database, must be unique. Example: `cc102` **data\_qualification\_service\_name** `string` Service name. Example: `Data validation` **status\_flow\_data\_qualification\_id** `integer` Data qualification status ID. Example: `1` **data\_qualification\_status\_flow\_name** `string` Data qualification status name. Example: `Processing` **description\_status** `string` Data qualification status description. Example: `Processando` **name** `string` Beneficiary name. Example: `Maria Jose` **document** `string` Beneficiary document. Example: `12345678909` **bank\_code** `string` Bank code. Example: `104` **bank\_branch** `string` Bank branch. Example: `0123` **bank\_branch\_digit** `string` Bank branch digit. Example: `0` **account** `string` Bank account. Example: `123456` **account\_digit** `string` Bank account digit. Example: `1` **account\_type\_name** `string` Account type. Example: `Checking account` **amount** `number` Source amount. Example: `1.1` **created\_at** `string` Creation timestamp. Format: `YYYY-MM-DD HH:mm:ss` **updated\_at** `string` Last update timestamp. Format: `YYYY-MM-DD HH:mm:ss` **merchant** `object` Merchant information. **Merchant Object** **id** `string` Merchant ID. **name** `string` Merchant name. ## Request Example ```bash cURL theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification/custom-code/DQ001' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' ``` ```javascript JavaScript theme={null} async function getDataQualificationByCustomCode(customCode) { const response = await fetch( `https://api.sandbox.wepayout.com.br/v1/payout/data-qualification/custom-code/${customCode}`, { method: 'GET', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer {token}' } } ); if (!response.ok) { throw new Error(`Failed to fetch data qualification: ${response.statusText}`); } return await response.json(); } const qualification = await getDataQualificationByCustomCode('DQ001'); console.log('Data qualification:', qualification); ``` ```python Python theme={null} import requests def get_data_qualification_by_custom_code(custom_code): url = f'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification/custom-code/{custom_code}' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer {token}' } response = requests.get(url, headers=headers) response.raise_for_status() return response.json() qualification = get_data_qualification_by_custom_code('DQ001') print('Data qualification:', qualification) ``` ```json 200 OK theme={null} { "id": 123, "batch_code": "abc101", "custom_code": "DQ001", "data_qualification_service_name": "Data validation", "status_flow_data_qualification_id": 1, "data_qualification_status_flow_name": "Processing", "description_status": "Processando", "name": "Maria Jose", "document": "12345678909", "bank_code": "104", "bank_branch": "0123", "bank_branch_digit": "0", "account": "123456", "account_digit": "1", "account_type_name": "Checking account", "amount": 1.1, "created_at": "2024-01-15 10:30:00", "updated_at": "2024-01-15 10:35:00", "merchant": { "id": "1", "name": "My Merchant" } } ``` # Get Data Qualification By ID Source: https://docs.wepayout.co/api-reference/data-qualification/get-by-id GET /v1/payout/data-qualification/{id} Retrieve information for a specific data qualification process ## Path Parameters **id** `integer` *required* The data qualification ID. ## Response **id** `integer` Our ID. Example: `123` **batch\_code** `string` Batch code. Example: `abc101` **custom\_code** `string` Your ID in our database, must be unique. Example: `cc102` **data\_qualification\_service\_name** `string` Service name. Example: `Data validation` **status\_flow\_data\_qualification\_id** `integer` Data qualification status ID. Example: `1` **data\_qualification\_status\_flow\_name** `string` Data qualification status name. Example: `Processing` **description\_status** `string` Data qualification status description. Example: `Processando` **name** `string` Beneficiary name. Example: `Maria Jose` **document** `string` Beneficiary document. Example: `12345678909` **bank\_code** `string` Bank code. Example: `104` **bank\_branch** `string` Bank branch. Example: `0123` **bank\_branch\_digit** `string` Bank branch digit. Example: `0` **account** `string` Bank account. Example: `123456` **account\_digit** `string` Bank account digit. Example: `1` **account\_type\_name** `string` Account type. Example: `Checking account` **amount** `number` Source amount. Example: `1.1` **created\_at** `string` Creation timestamp. Format: `YYYY-MM-DD HH:mm:ss` **updated\_at** `string` Last update timestamp. Format: `YYYY-MM-DD HH:mm:ss` **merchant** `object` Merchant information. **Merchant Object** **id** `string` Merchant ID. **name** `string` Merchant name. ## Request Example ```bash cURL theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification/123' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' ``` ```javascript JavaScript theme={null} async function getDataQualificationById(id) { const response = await fetch( `https://api.sandbox.wepayout.com.br/v1/payout/data-qualification/${id}`, { method: 'GET', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer {token}' } } ); if (!response.ok) { throw new Error(`Failed to fetch data qualification: ${response.statusText}`); } return await response.json(); } const qualification = await getDataQualificationById(123); console.log('Data qualification:', qualification); ``` ```python Python theme={null} import requests def get_data_qualification_by_id(qualification_id): url = f'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification/{qualification_id}' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer {token}' } response = requests.get(url, headers=headers) response.raise_for_status() return response.json() qualification = get_data_qualification_by_id(123) print('Data qualification:', qualification) ``` ```json 200 OK theme={null} { "id": 123, "batch_code": "abc101", "custom_code": "cc102", "data_qualification_service_name": "Data validation", "status_flow_data_qualification_id": 1, "data_qualification_status_flow_name": "Processing", "description_status": "Processando", "name": "Maria Jose", "document": "12345678909", "bank_code": "104", "bank_branch": "0123", "bank_branch_digit": "0", "account": "123456", "account_digit": "1", "account_type_name": "Checking account", "amount": 1.1, "created_at": "2024-01-15 10:30:00", "updated_at": "2024-01-15 10:35:00", "merchant": { "id": "1", "name": "My Merchant" } } ``` # Get Data Qualification Services Source: https://docs.wepayout.co/api-reference/data-qualification/get-services GET /v1/payout/data-qualification/services Retrieve available data qualification services The data qualification services determine the procedures that will be applied to qualify the bank account. ## Available Services We have five data qualification services available: * **1** - Automatic validation: validates the document and bank account digits. * **2** - Automatic validation + micro deposit: After the data is validated a micro deposit is made to the account to assure that it's valid. * **3** - Automatic validation + micro deposit + manual correction: Same as above plus manual check in case of failures. * **4** - Automatic validation + deposit: Same as 2 but you provide the amount to be deposited. * **5** - Automatic validation + deposit + manual correction: Same as 3 but you provide the amount to be deposited. ## Response **array** `array` Array of data qualification services. **Service Object** **id** `integer` Service identifier. Example: `1` **name** `string` Service name. Example: `Data qualification manually` ## Request Example ```bash cURL theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification/services' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' ``` ```javascript JavaScript theme={null} async function getDataQualificationServices() { const response = await fetch( 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification/services', { method: 'GET', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer {token}' } } ); if (!response.ok) { throw new Error(`Failed to fetch services: ${response.statusText}`); } return await response.json(); } const services = await getDataQualificationServices(); console.log('Available services:', services); ``` ```python Python theme={null} import requests def get_data_qualification_services(): url = 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification/services' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer {token}' } response = requests.get(url, headers=headers) response.raise_for_status() return response.json() services = get_data_qualification_services() print('Available services:', services) ``` ```json 200 OK theme={null} [ { "id": 1, "name": "Data qualification manually" }, { "id": 2, "name": "Automatic validation + micro deposit" }, { "id": 3, "name": "Automatic validation + micro deposit + manual correction" }, { "id": 4, "name": "Automatic validation + deposit" }, { "id": 5, "name": "Automatic validation + deposit + manual correction" } ] ``` # Get Data Qualification Statuses Source: https://docs.wepayout.co/api-reference/data-qualification/get-status GET /v1/payout/data-qualification/status Retrieve all available data qualification statuses ## Status Descriptions * **1** - Received: Payment received and stored in our database * **5** - Valid data: The account data is valid * **6** - Invalid data: Payment rejected by the bank * **7** - Validation not possible on this step: The account data provided can not be validated * **9** - Awaiting: Awaiting balance to be processed * **999** - Processing: Payment sent for processing ## Query Parameters **per\_page** `integer` The number of items that will be displayed per page on paginated lists. Min: `0` **page** `integer` The current page that will be displayed on paginated lists. Min: `0` ## Response **array** `array` Array of status objects. **Status Object** **id** `integer` Status ID. Example: `1` **name** `string` Status name. Example: `received` ## Request Example ```bash cURL theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification/status' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' ``` ```bash cURL - With Pagination theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification/status?page=1&per_page=10' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' ``` ```javascript JavaScript theme={null} async function getDataQualificationStatuses() { const response = await fetch( 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification/status', { method: 'GET', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer {token}' } } ); if (!response.ok) { throw new Error(`Failed to fetch statuses: ${response.statusText}`); } return await response.json(); } const statuses = await getDataQualificationStatuses(); console.log('Available statuses:', statuses); ``` ```python Python theme={null} import requests def get_data_qualification_statuses(): url = 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification/status' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer {token}' } response = requests.get(url, headers=headers) response.raise_for_status() return response.json() statuses = get_data_qualification_statuses() print('Available statuses:', statuses) ``` ```json 200 OK theme={null} [ { "id": 1, "name": "received" }, { "id": 5, "name": "valid_data" }, { "id": 6, "name": "invalid_data" }, { "id": 7, "name": "validation_not_possible" }, { "id": 9, "name": "awaiting" }, { "id": 999, "name": "processing" } ] ``` # List Data Qualifications Source: https://docs.wepayout.co/api-reference/data-qualification/list-data-qualification GET /v1/payout/data-qualification Retrieve a paginated, filterable and sortable list of data qualification processes A paginated, filterable and sortable list of data qualification processes. ## Query Parameters **per\_page** `integer` The number of items that will be displayed per page on paginated lists. Min: `0` **page** `integer` The current page that will be displayed on paginated lists. Min: `0` **order\_by** `string` The field that will be used to sort data. Allowed values: `id`, `data_qualification_service_name`, `batch_code`, `custom_code`, `merchant.name`, `description_status`, `created_at` Default: `id` **sort** `string` The sort type. Allowed values: `asc`, `desc` Default: `asc` **created\_at** `string` Created at filter. Example: `2020-01-01` **custom\_code** `string` Filter by custom\_code (invoice). Example: `abc001` **document** `string` Filter by the beneficiary's document. Example: `00000000000` **data\_qualification\_service\_id** `integer` Filter by qualification service. You can list the available options in the endpoint [GET /v1/payout/data-qualification/services](/api-reference/data-qualification/get-services). **merchant\_id** `integer` Filter by merchant\_id. **status\_flow\_data\_qualification\_id** `string` Filter by status. You can list the available options in the endpoint [GET /v1/payout/data-qualification/status](/api-reference/data-qualification/get-status). ## Response **array** `array` Array of data qualification records. **Data Qualification Object** **id** `integer` Our ID. Example: `123` **batch\_code** `string` Batch code. Example: `abc101` **custom\_code** `string` Your ID in our database, must be unique. Example: `cc102` **data\_qualification\_service\_name** `string` Service name. Example: `Data validation` **status\_flow\_data\_qualification\_id** `integer` Data qualification status ID. Example: `1` **data\_qualification\_status\_flow\_name** `string` Data qualification status name. Example: `Processing` **description\_status** `string` Data qualification status description. Example: `Processando` **name** `string` Beneficiary name. Example: `Maria Jose` **document** `string` Beneficiary document. Example: `12345678909` **bank\_code** `string` Bank code. Example: `104` **bank\_branch** `string` Bank branch. Example: `0123` **bank\_branch\_digit** `string` Bank branch digit. Example: `0` **account** `string` Bank account. Example: `123456` **account\_digit** `string` Bank account digit. Example: `1` **account\_type\_name** `string` Account type. Example: `Checking account` **amount** `number` Source amount. Example: `1.1` **created\_at** `string` Creation timestamp. Format: `YYYY-MM-DD HH:mm:ss` **updated\_at** `string` Last update timestamp. Format: `YYYY-MM-DD HH:mm:ss` **merchant** `object` Merchant information. **Merchant Object** **id** `string` Merchant ID. **name** `string` Merchant name. ## Request Example ```bash cURL - All Records theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' ``` ```bash cURL - With Filters theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification?page=1&per_page=10&order_by=created_at&sort=desc&status_flow_data_qualification_id=1' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' ``` ```bash cURL - Filter by Document theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification?document=12345678909' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {token}' ``` ```javascript JavaScript theme={null} async function listDataQualifications(filters = {}) { const params = new URLSearchParams(filters); const response = await fetch( `https://api.sandbox.wepayout.com.br/v1/payout/data-qualification?${params}`, { method: 'GET', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer {token}' } } ); if (!response.ok) { throw new Error(`Failed to fetch data qualifications: ${response.statusText}`); } return await response.json(); } const qualifications = await listDataQualifications({ page: 1, per_page: 10, order_by: 'created_at', sort: 'desc' }); console.log('Data qualifications:', qualifications); ``` ```python Python theme={null} import requests def list_data_qualifications(filters=None): url = 'https://api.sandbox.wepayout.com.br/v1/payout/data-qualification' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer {token}' } response = requests.get(url, headers=headers, params=filters) response.raise_for_status() return response.json() qualifications = list_data_qualifications({ 'page': 1, 'per_page': 10, 'order_by': 'created_at', 'sort': 'desc' }) print('Data qualifications:', qualifications) ``` ```json 200 OK theme={null} [ { "id": 123, "batch_code": "abc101", "custom_code": "cc102", "data_qualification_service_name": "Data validation", "status_flow_data_qualification_id": 1, "data_qualification_status_flow_name": "Processing", "description_status": "Processando", "name": "Maria Jose", "document": "12345678909", "bank_code": "104", "bank_branch": "0123", "bank_branch_digit": "0", "account": "123456", "account_digit": "1", "account_type_name": "Checking account", "amount": 1.1, "created_at": "2024-01-15 10:30:00", "updated_at": "2024-01-15 10:35:00", "merchant": { "id": "1", "name": "My Merchant" } } ] ``` # Get KYC By ID Source: https://docs.wepayout.co/api-reference/kyc/get GET /v1/kyc/{id} This route is performed using the KYC ID. If a KYC with the provided ID exists, it will be retrieved; otherwise, an empty response will be returned. # Get KYC By ID This route is performed using the KYC ID. If a KYC with the provided ID exists, it will be retrieved; otherwise, an empty response will be returned. ## Path Parameters **id** `string` *required* KYC ID ## Response **id** `integer` Unique identifier for the KYC record. **origin\_request** `string` Identifier or reference of the original request that triggered this KYC process. Example: `PAYIN` or `PAYOUT` **description** `string` Textual description or details about the KYC request. **info\_add** `string` Additional information. **created\_at** `string` Date and time when the KYC record was created. Format: `YYYY-MM-DD HH:mm:ss` **updated\_at** `string` Date and time of the last update made to this KYC record. Format: `YYYY-MM-DD HH:mm:ss` **merchant** `string` Name of the main merchant associated with the KYC process. **submerchant** `string` Name of the submerchant involved in the KYC process. **status** `object` Object representing the current status of the KYC. **Status Object** **id** `integer` Status identifier. Example: `1` **name** `string` Name of the status. Example: `Waiting Upload Documents`, `Waiting Approval Documents`, `Approved`, `Pending Regularization` or `Canceled` **reason** `object` Object representing the reason for the KYC request. **Reason Object** **id** `integer` Reason identifier. **name** `string` Name or description of the reason. Example: `Payout: Limit BRL 100K Usual` **persons** `array` List of people or entities involved in the KYC process. **Person Object** **id** `integer` Unique identifier of the person. **name** `string` Common or display name of the person. **legal\_name** `string` Legal name. **document** `string` Document number. **type\_person** `string` Type of person. Example: `Beneficiary` **document\_required** `array` List of required document types for this person. **Document Required Object** **status** `boolean` Indicates whether this document is required for the KYC process. **label** `string` Display label for the required document. **documents** `array` List of uploaded documents related to the KYC. **Document Object** **id** `integer` Unique identifier of the uploaded document. **status\_id** `integer` Current validation status ID. **status\_name** `string` Name of the status. **document\_id** `integer` ID of the uploaded document. **document\_name** `string` Name of the document. **collection\_name** `string` Name of the document collection or group, if applicable. **collection\_id** `integer` Identifier of the document collection. **value\_field** `string` URL for downloading the uploaded document file. **rejection\_reason** `string` Reason for rejection if the document was not approved. **label** `string` Label or description used to identify the document field. **type\_field** `string` Input type. Example: `file` or `text` **required\_field** `boolean` Whether this document is required for KYC completion. **expires\_at** `string` Expiration date of the document. **automaticatic\_validation** `integer` Indicates if the document supports automatic validation. Example: `1` = yes, `0` = no ## Request Example ```bash cURL theme={null} curl --request GET \ --url '"https://api.sandbox.wepayout.com.br/v1/kyc/{id}"' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` ```javascript JavaScript theme={null} async function getKYCById(kycId) { const response = await fetch( `https://api.sandbox.wepayout.com.br/v1/kyc/${kycId}`, { method: 'GET', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer 123' } } ); if (!response.ok) { throw new Error(`Failed to fetch KYC: ${response.statusText}`); } return await response.json(); } // Usage const kyc = await getKYCById(123); console.log('KYC details:', kyc); ``` ```python Python theme={null} import requests def get_kyc_by_id(kyc_id): url = f'https://api.sandbox.wepayout.com.br/v1/kyc/{kyc_id}' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer 123' } response = requests.get(url, headers=headers) response.raise_for_status() return response.json() # Usage kyc = get_kyc_by_id(123) print('KYC details:', kyc) ``` ```json 200 OK theme={null} { "id": 348, "origin_request": "PAYOUT", "description": " Compliance approved KYC without document upload", "info_add": null, "created_at": "2022-06-14 17:15:41", "updated_at": "2023-10-03 16:01:28", "merchant": "Merchant Name", "submerchant": null, "status": { "id": 3, "name": "Approved" }, "reason": { "id": 17, "name": "Payout: Limit BRL 100K Usual" }, "persons": [ { "id": 390, "name": "Person name", "legal_name": null, "document": "83562580061", "type_person": "Beneficiary" } ], "document_required": [ { "status": true, "label": "Document proving the origin and destination of the operation" }, { "status": true, "label": "Proof of residence" }, { "status": true, "label": "Personal document" }, { "status": true, "label": "Beneficiary Full Name" }, { "status": true, "label": "Email" }, { "status": true, "label": "Phone" }, { "status": true, "label": "Nationality" }, { "status": true, "label": "Profession (Occupation)" } ], "documents": [ { "id": 652, "status_id": 3, "status_name": "Approved", "document_id": 1, "document_name": "invoice", "collection_name": null, "collection_id": null, "value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file", "rejection_reason": null, "label": "Document proving the origin and destination of the operation", "type_field": "file", "required_field": true, "expires_at": null, "automaticatic_validation": 0 }, { "id": 653, "status_id": 3, "status_name": "Approved", "document_id": 2, "document_name": "address", "collection_name": null, "collection_id": null, "value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file", "rejection_reason": null, "label": "Proof of residence", "type_field": "file", "required_field": true, "expires_at": null, "automaticatic_validation": 0 }, { "id": 654, "status_id": 3, "status_name": "Approved", "document_id": 3, "document_name": "personal-document", "collection_name": null, "collection_id": null, "value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file", "rejection_reason": null, "label": "Personal document", "type_field": "file", "required_field": true, "expires_at": null, "automaticatic_validation": 0 }, { "id": 655, "status_id": 3, "status_name": "Approved", "document_id": 5, "document_name": "full-name-beneficiary", "collection_name": null, "collection_id": null, "value_field": null, "rejection_reason": null, "label": "Beneficiary Full Name", "type_field": "text", "required_field": true, "expires_at": null, "automaticatic_validation": 0 }, { "id": 656, "status_id": 3, "status_name": "Approved", "document_id": 7, "document_name": "email", "collection_name": null, "collection_id": null, "value_field": null, "rejection_reason": null, "label": "Email", "type_field": "text", "required_field": true, "expires_at": null, "automaticatic_validation": 0 }, { "id": 657, "status_id": 3, "status_name": "Approved", "document_id": 8, "document_name": "phone", "collection_name": null, "collection_id": null, "value_field": null, "rejection_reason": null, "label": "Phone", "type_field": "text", "required_field": true, "expires_at": null, "automaticatic_validation": 0 }, { "id": 658, "status_id": 3, "status_name": "Approved", "document_id": 11, "document_name": "nationality", "collection_name": null, "collection_id": null, "value_field": null, "rejection_reason": null, "label": "Nationality", "type_field": "text", "required_field": true, "expires_at": null, "automaticatic_validation": 0 }, { "id": 659, "status_id": 3, "status_name": "Approved", "document_id": 9, "document_name": "profession", "collection_name": null, "collection_id": null, "value_field": null, "rejection_reason": null, "label": "Profession (Occupation)", "type_field": "text", "required_field": true, "expires_at": null, "automaticatic_validation": 0 } ] } ``` ```json 404 Not Found theme={null} { "error": "KYC not found", "message": "No KYC record found with the provided ID" } ``` ## Related Resources > [card] [List KYC](/api-reference/kyc/list-kyc) > > List all KYC verifications > [card] [Get Balance](/api-reference/account/get-balance) > > Check account balance > [card] [Create Charge](/api-reference/cash-in/payin/create-charge) > > Create a new charge > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Create a payout payment # Get KYC By Document Source: https://docs.wepayout.co/api-reference/kyc/get-by-document POST /v1/kyc/document/{cpf_or_cnpj} This data can be used in the "kyc-proof-url" of a KYC. If no document is found for this cpf/cnpj, the request will return an empty array. If a KYC with the provided document exists, only the most recent KYC record for that document will be returned. When you provide a cpf or cnpj, you will be informed. # Get KYC By Document This data can be used in the "kyc-proof-url" of a KYC. If no document is found for this cpf/cnpj, the request will return an empty array. If a KYC with the provided document exists, only the most recent KYC record for that document will be returned. When you provide a cpf or cnpj, you will be informed. ## Path Parameters **cpf\_or\_cnpj** `string` *required* CPF or CNPJ document number ## Body **document** `string` *required* Provide either a CPF or CNPJ number (digits only, no special characters) ## Response **id** `integer` Unique identifier for the KYC record. **origin\_request** `string` Identifier or reference of the original request that triggered this KYC process. Example: `PAYIN` or `PAYOUT` **description** `string` Textual description or details about the KYC request. **info\_add** `string` Additional information. **created\_at** `string` Date and time when the KYC record was created. Format: `YYYY-MM-DD HH:mm:ss` **updated\_at** `string` Date and time of the last update made to this KYC record. Format: `YYYY-MM-DD HH:mm:ss` **merchant** `string` Name of the main merchant associated with the KYC process. **submerchant** `string` Name of the submerchant involved in the KYC process. **status** `object` Object representing the current status of the KYC. **Status Object** **id** `integer` Status identifier. Example: `1` **name** `string` Name of the status. Example: `Waiting Upload Documents`, `Waiting Approval Documents`, `Approved`, `Pending Regularization` or `Canceled` **reason** `object` Object representing the reason for the KYC request. **Reason Object** **id** `integer` Reason identifier. **name** `string` Name or description of the reason. Example: `Payout: Limit BRL 100K Usual` **persons** `array` List of people or entities involved in the KYC process. **Person Object** **id** `integer` Unique identifier of the person. **name** `string` Common or display name of the person. **legal\_name** `string` Legal name. **document** `string` Document number. **type\_person** `string` Type of person. Example: `Beneficiary` **document\_required** `array` List of required document types for this person. **Document Required Object** **status** `boolean` Indicates whether this document is required for the KYC process. **label** `string` Display label for the required document. **documents** `array` List of uploaded documents related to the KYC. **Document Object** **id** `integer` Unique identifier of the uploaded document. **status\_id** `integer` Current validation status ID. **status\_name** `string` Name of the status. **document\_id** `integer` ID of the uploaded document. **document\_name** `string` Name of the document. **collection\_name** `string` Name of the document collection or group, if applicable. **collection\_id** `integer` Identifier of the document collection. **value\_field** `string` URL for downloading the uploaded document file. **rejection\_reason** `string` Reason for rejection if the document was not approved. **label** `string` Label or description used to identify the document field. **type\_field** `string` Input type. Example: `file` or `text` **required\_field** `boolean` Whether this document is required for KYC completion. **expires\_at** `string` Expiration date of the document. **automaticatic\_validation** `integer` Indicates if the document supports automatic validation. Example: `1` = yes, `0` = no ## Request Example ```bash cURL - CPF theme={null} curl --request POST \ --url 'https://api.sandbox.wepayout.com.br/v1/kyc/document/12345678900' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' \ --header 'Content-Type: application/json' \ --data '{ "document": "12345678901" }' ``` ```bash cURL - CNPJ theme={null} curl --request POST \ --url 'https://api.sandbox.wepayout.com.br/v1/kyc/document/12345678000190' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' \ --header 'Content-Type: application/json' \ --data '{ "document": "12345678000190" }' ``` ```javascript JavaScript theme={null} async function getKYCByDocument(document) { const response = await fetch( `https://api.sandbox.wepayout.com.br/v1/kyc/document/${document}`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer 123', 'Content-Type': 'application/json' }, body: JSON.stringify({ document: document }) } ); if (!response.ok) { throw new Error(`Failed to fetch KYC: ${response.statusText}`); } return await response.json(); } // Usage - CPF const kycByCPF = await getKYCByDocument('12345678900'); console.log('KYC by CPF:', kycByCPF); // Usage - CNPJ const kycByCNPJ = await getKYCByDocument('12345678000190'); console.log('KYC by CNPJ:', kycByCNPJ); ``` ```python Python theme={null} import requests def get_kyc_by_document(document): url = f'https://api.sandbox.wepayout.com.br/v1/kyc/document/{document}' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer 123', 'Content-Type': 'application/json' } data = { 'document': document } response = requests.post(url, headers=headers, json=data) response.raise_for_status() return response.json() # Usage - CPF kyc_by_cpf = get_kyc_by_document('12345678900') print('KYC by CPF:', kyc_by_cpf) # Usage - CNPJ kyc_by_cnpj = get_kyc_by_document('12345678000190') print('KYC by CNPJ:', kyc_by_cnpj) ``` ```json 200 OK theme={null} { "id": 348, "origin_request": "PAYOUT", "description": " Compliance approved KYC without document upload", "info_add": null, "created_at": "2022-06-14 17:15:41", "updated_at": "2023-10-03 16:01:28", "merchant": "Merchant Name", "submerchant": null, "status": { "id": 3, "name": "Approved" }, "reason": { "id": 17, "name": "Payout: Limit BRL 100K Usual" }, "persons": [ { "id": 390, "name": "Person name", "legal_name": null, "document": "83562580061", "type_person": "Beneficiary" } ], "document_required": [ { "status": true, "label": "Document proving the origin and destination of the operation" }, { "status": true, "label": "Proof of residence" }, { "status": true, "label": "Personal document" }, { "status": true, "label": "Beneficiary Full Name" }, { "status": true, "label": "Email" }, { "status": true, "label": "Phone" }, { "status": true, "label": "Nationality" }, { "status": true, "label": "Profession (Occupation)" } ], "documents": [ { "id": 652, "status_id": 3, "status_name": "Approved", "document_id": 1, "document_name": "invoice", "collection_name": null, "collection_id": null, "value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file", "rejection_reason": null, "label": "Document proving the origin and destination of the operation", "type_field": "file", "required_field": true, "expires_at": null, "automaticatic_validation": 0 }, { "id": 653, "status_id": 3, "status_name": "Approved", "document_id": 2, "document_name": "address", "collection_name": null, "collection_id": null, "value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file", "rejection_reason": null, "label": "Proof of residence", "type_field": "file", "required_field": true, "expires_at": null, "automaticatic_validation": 0 }, { "id": 654, "status_id": 3, "status_name": "Approved", "document_id": 3, "document_name": "personal-document", "collection_name": null, "collection_id": null, "value_field": "https://bucket-name.s3.us-east-1.amazonaws.com/path/to/file", "rejection_reason": null, "label": "Personal document", "type_field": "file", "required_field": true, "expires_at": null, "automaticatic_validation": 0 }, { "id": 655, "status_id": 3, "status_name": "Approved", "document_id": 5, "document_name": "full-name-beneficiary", "collection_name": null, "collection_id": null, "value_field": null, "rejection_reason": null, "label": "Beneficiary Full Name", "type_field": "text", "required_field": true, "expires_at": null, "automaticatic_validation": 0 }, { "id": 656, "status_id": 3, "status_name": "Approved", "document_id": 7, "document_name": "email", "collection_name": null, "collection_id": null, "value_field": null, "rejection_reason": null, "label": "Email", "type_field": "text", "required_field": true, "expires_at": null, "automaticatic_validation": 0 }, { "id": 657, "status_id": 3, "status_name": "Approved", "document_id": 8, "document_name": "phone", "collection_name": null, "collection_id": null, "value_field": null, "rejection_reason": null, "label": "Phone", "type_field": "text", "required_field": true, "expires_at": null, "automaticatic_validation": 0 }, { "id": 658, "status_id": 3, "status_name": "Approved", "document_id": 11, "document_name": "nationality", "collection_name": null, "collection_id": null, "value_field": null, "rejection_reason": null, "label": "Nationality", "type_field": "text", "required_field": true, "expires_at": null, "automaticatic_validation": 0 }, { "id": 659, "status_id": 3, "status_name": "Approved", "document_id": 9, "document_name": "profession", "collection_name": null, "collection_id": null, "value_field": null, "rejection_reason": null, "label": "Profession (Occupation)", "type_field": "text", "required_field": true, "expires_at": null, "automaticatic_validation": 0 } ] } ``` ```json 200 OK - Empty Array theme={null} [] ``` ```json 404 Not Found theme={null} { "message": "Not found" } ``` ## Use Cases > [accordion] Search KYC by Document > > Retrieve KYC information using a CPF or CNPJ document: > > ```javascript theme={null} > async function searchByDocument(document) { > try { > const kyc = await getKYCByDocument(document); > > if (Array.isArray(kyc) && kyc.length === 0) { > console.log('No KYC found for this document'); > return null; > } > > const person = kyc.persons[0]; > console.log(`Found KYC for ${person.name}`); > console.log(`Document: ${person.document}`); > console.log(`Status: ${kyc.status.name}`); > console.log(`Reason: ${kyc.reason.name}`); > > return kyc; > } catch (error) { > console.error('Error searching KYC:', error); > } > } > ``` > [accordion] Check Document Status > > Check the status and documents for a specific document number: > > ```javascript theme={null} > async function checkDocumentStatus(document) { > try { > const kyc = await getKYCByDocument(document); > > if (Array.isArray(kyc) && kyc.length === 0) { > return { found: false }; > } > > const approvedDocs = kyc.documents.filter(doc => doc.status_id === 3); > > return { > found: true, > status: kyc.status.name, > totalDocuments: kyc.documents.length, > approvedDocuments: approvedDocs.length, > persons: kyc.persons.map(p => p.name) > }; > } catch (error) { > console.error('Error checking document status:', error); > } > } > ``` > [accordion] Validate Document Before Transaction > > Check if a document has an approved KYC before processing a transaction: > > ```javascript theme={null} > async function validateDocumentForTransaction(document) { > const kyc = await getKYCByDocument(document); > > if (Array.isArray(kyc) && kyc.length === 0) { > return { > valid: false, > reason: 'No KYC record found' > }; > } > > const isApproved = kyc.status.id === 3; > > return { > valid: isApproved, > kycId: kyc.id, > status: kyc.status.name, > reason: isApproved ? 'KYC approved' : `KYC status: ${kyc.status.name}` > }; > } > > // Usage > const validation = await validateDocumentForTransaction('12345678900'); > if (validation.valid) { > console.log('Document validated, proceed with transaction'); > } else { > console.log(`Cannot proceed: ${validation.reason}`); > } > ``` > [accordion] Get Most Recent KYC > > Since this endpoint returns only the most recent KYC, use it to check current status: > > ```javascript theme={null} > async function getMostRecentKYC(document) { > const kyc = await getKYCByDocument(document); > > if (Array.isArray(kyc) && kyc.length === 0) { > return null; > } > > const person = kyc.persons[0]; > > return { > id: kyc.id, > person: person.name, > document: person.document, > personType: person.type_person, > status: kyc.status.name, > reason: kyc.reason.name, > lastUpdate: kyc.updated_at, > createdAt: kyc.created_at > }; > } > ``` ## Best Practices > [!NOTE] > > **Document Format**: Send only digits in the document field, without special characters like dots, hyphens, or slashes. > [!WARNING] > > **Most Recent Record**: This endpoint returns only the most recent KYC record for the provided document. If you need historical records, use the List KYC endpoint. > [!TIP] > > **Empty Array**: An empty array response indicates no KYC record exists for the provided document, which is different from a 404 error. ## Related Resources > [card] [List KYC](/api-reference/kyc/list-kyc) > > List all KYC verifications > [card] [Get KYC By ID](/api-reference/kyc/get) > > Get KYC by ID > [card] [Create Charge](/api-reference/cash-in/payin/create-charge) > > Create a new charge > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Create a payout payment # List KYC Source: https://docs.wepayout.co/api-reference/kyc/list-kyc GET /v1/kyc Retrieves a list of pending KYC verifications # List KYC Retrieves a list of pending KYC verifications. > [!NOTE] > > **Status**: You can filter KYC results by using the `status_id` query parameter at the KYC listing endpoint. Below are the available status values. ## Status Table | TENDER ID | STATUS NAME | | - | - | | 1 | Awaiting Upload Documents | | 2 | Awaiting Approval Documents | | 3 | Approved | | 4 | Pending Regularization | | 5 | Canceled | ## Query Parameters **page** `string` The current number you wish to view. **per\_page** `string` The maximum number of items shown per page. **sort** `string` Sort order. Allowed values: `0`, `1`, `2`, `3`, `4`, `5` **status\_id** `string` Status filter. Allowed values: `1`, `2`, `3`, `4`, `5` ## Response **array** `array` Array of KYC records. **KYC Object** **id** `integer` Unique identifier for the KYC record. **origin\_request** `string` Identifier or reference of the original request that triggered this KYC process. Example: `PAYIN or REQUEST` **description** `string` Textual description or details about the KYC request. **notes** `string` Additional notes or observations about the KYC request. **created\_at** `string` Date and time of the KYC record was created. Format: `YYYY-MM-DD HH:mm:ss` **updated\_at** `string` Date and time of the last update made to this KYC record. Format: `YYYY-MM-DD HH:mm:ss` **merchant** `string` Name of the main merchant associated with the KYC process. **submerchant** `string` Identifier of the submerchant involved in the KYC process. **status** `object` Object representing the current status of the KYC. **Status Object** **id** `integer` Status identifier. Example: `1` **name** `string` Name of the status. Example: `Waiting Upload Documents`, `Waiting Approval Documents`, `Approved`, `Pending Regularization` or `Canceled` **beneficiary** `object` Object with information about the person or entity being verified. **Beneficiary Object** **id** `integer` Beneficiary identifier. **name** `string` Name of the beneficiary. **document** `string` Document number used for identification. ## Request Example ```bash cURL - All KYC theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v1/kyc' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` ```bash cURL - Filter by Status theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v1/kyc?status_id=1' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` ```bash cURL - With Pagination theme={null} curl --request GET \ --url 'https://api.sandbox.wepayout.com.br/v1/kyc?page=1&per_page=10' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' ``` ```javascript JavaScript theme={null} async function listKYC(filters = {}) { const params = new URLSearchParams({ page: filters.page || 1, per_page: filters.perPage || 10, ...filters }); const response = await fetch( `https://api.sandbox.wepayout.com.br/v1/kyc?${params}`, { method: 'GET', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer 123' } } ); return await response.json(); } // Usage examples // List all KYC records const allKYC = await listKYC(); // Filter by status const pendingKYC = await listKYC({ status_id: 1 }); // With pagination const page1 = await listKYC({ page: 1, per_page: 10 }); console.log('KYC records:', allKYC); ``` ```python Python theme={null} import requests def list_kyc(filters=None): url = 'https://api.sandbox.wepayout.com.br/v1/kyc' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer 123' } params = { 'page': 1, 'per_page': 10 } if filters: params.update(filters) response = requests.get(url, headers=headers, params=params) return response.json() # Usage examples # List all KYC records all_kyc = list_kyc() # Filter by status pending_kyc = list_kyc({'status_id': 1}) # With pagination page_1 = list_kyc({'page': 1, 'per_page': 10}) print('KYC records:', all_kyc) ``` ```json 200 OK theme={null} [ { "id": 1563, "origin_request": "PAYIN", "description": "test", "notes": null, "created_at": "2025-05-19 10:53:48", "updated_at": "2025-05-19 10:53:48", "merchant": "Merchant's name", "submerchant": null, "status": { "id": 1, "name": "Waiting Upload Documents" }, "beneficiary": { "id": 1691, "name": "TEST", "document": "12345678987" } } ] ``` ## Use Cases > [accordion] Monitor Pending KYC Verifications > > Track all KYC verifications that are awaiting document upload: > > ```javascript theme={null} > async function getPendingKYC() { > const pending = await listKYC({ status_id: 1 }); > > console.log(`Found ${pending.length} pending KYC verifications`); > > pending.forEach(kyc => { > console.log(`- ${kyc.beneficiary.name}: ${kyc.status.name}`); > }); > > return pending; > } > ``` > [accordion] Filter by Origin Request > > Get KYC records by origin (PAYIN or REQUEST): > > ```javascript theme={null} > async function getKYCByOrigin(origin) { > const allKYC = await listKYC(); > > return allKYC.filter(kyc => kyc.origin_request === origin); > } > > // Get all PAYIN-related KYC > const payinKYC = await getKYCByOrigin('PAYIN'); > ``` > [accordion] Track KYC Status Changes > > Monitor KYC status changes over time: > > ```javascript theme={null} > async function trackKYCStatus(kycId) { > const allKYC = await listKYC(); > const kyc = allKYC.find(k => k.id === kycId); > > if (!kyc) { > throw new Error('KYC not found'); > } > > return { > id: kyc.id, > beneficiary: kyc.beneficiary.name, > currentStatus: kyc.status.name, > lastUpdate: kyc.updated_at, > origin: kyc.origin_request > }; > } > ``` > [accordion] Generate KYC Report > > Generate a report of all KYC verifications by status: > > ```javascript theme={null} > async function generateKYCReport() { > const allKYC = await listKYC(); > > const report = { > total: allKYC.length, > byStatus: {}, > byOrigin: {} > }; > > allKYC.forEach(kyc => { > // Count by status > const statusName = kyc.status.name; > report.byStatus[statusName] = (report.byStatus[statusName] || 0) + 1; > > // Count by origin > const origin = kyc.origin_request; > report.byOrigin[origin] = (report.byOrigin[origin] || 0) + 1; > }); > > return report; > } > > // Usage > const report = await generateKYCReport(); > console.log('KYC Report:', report); > // Output: { total: 50, byStatus: { 'Approved': 30, 'Pending': 20 }, byOrigin: { 'PAYIN': 35, 'REQUEST': 15 } } > ``` ## Status Workflow ```mermaid theme={null} graph TD A[KYC Created] --> B[1 - Awaiting Upload Documents] B --> C[2 - Awaiting Approval Documents] C --> D{Approved?} D -->|Yes| E[3 - Approved] D -->|No| F[4 - Pending Regularization] F --> B B --> G[5 - Canceled] C --> G ``` ## Best Practices > [!NOTE] > > **Pagination**: Always use pagination when listing KYC records to avoid performance issues. The default page size is 10. > [!WARNING] > > **Status Monitoring**: Regularly check KYC status to ensure timely document uploads and approvals. > [!TIP] > > **Filter by Status**: Use the `status_id` parameter to filter KYC records by specific statuses and reduce response size. ## Related Resources > [card] [Get Balance](/api-reference/account/get-balance) > > Check account balance > [card] [Create Charge](/api-reference/cash-in/payin/create-charge) > > Create a new charge > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Create a payout payment > [card] [Get Statement](/api-reference/account/get-statement) > > View account statement # Submit Document For KYC Source: https://docs.wepayout.co/api-reference/kyc/submit-document POST /v1/kyc/documents/{documentId}/update Submit documents for a pending KYC verification # Submit Document For KYC This route is used to submit documents for a pending KYC. There are two types of documents that can be submitted: * **Text-type documents** * **File-type documents** Only one document can be updated at a time. > [!WARNING] > > **Attention point**: Supported extensions for file-type documents: `jpg`, `jpeg`, `gif`, `png` and `pdf` ## Path Parameters **documentId** `integer` *required* The ID of the document to update ## Body **value** `string` *required* The value to submit for the document. For file-type documents, provide the file URL. For text-type documents, provide the text value. ## Response **id** `integer` Unique identifier for the uploaded document record. **status\_id** `integer` Identifier of the current validation status of the document. **status\_name** `string` Name of the document's validation status. **document\_id** `integer` Identifier of the document. **document\_name** `string` Name of the document type uploaded. **collection\_name** `string` Name of the document collection or group. **collection\_id** `integer` Identifier of the document collection. **value\_field** `string` URL for downloading the uploaded document file. **rejection\_reason** `string` Reason for rejection if the document was not approved. **label** `string` Label or description used to identify the document field. **type\_field** `string` Type of input expected for this field. Example: `file` or `text` **required\_field** `boolean` Indicates whether this field is mandatory for completing the KYC process. **expires\_at** `string` Expiration date of the document, if applicable. Format: `` **automaticatic\_validation** `integer` Indicates whether the document is eligible for automatic validation. Example: `1` = yes, `0` = no ## Request Example ```bash cURL theme={null} curl --request POST \ --url https://api.sandbox.wepayout.com.br/v1/kyc/documents/{documentId}/update \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123' \ --header 'Content-Type: application/json' \ --data '{ "value": "string" }' ``` ```javascript JavaScript theme={null} async function submitKYCDocument(documentId, value) { const response = await fetch( `https://api.sandbox.wepayout.com.br/v1/kyc/documents/${documentId}/update`, { method: 'POST', headers: { 'Accept': 'application/json', 'Authorization': 'Bearer 123', 'Content-Type': 'application/json' }, body: JSON.stringify({ value: value }) } ); if (!response.ok) { throw new Error(`Failed to submit document: ${response.statusText}`); } return await response.json(); } // Usage - Submit file URL const fileResult = await submitKYCDocument(35, 'https://s3.amazonaws.com/bucket/file.pdf'); console.log('File document submitted:', fileResult); // Usage - Submit text value const textResult = await submitKYCDocument(36, 'John Doe'); console.log('Text document submitted:', textResult); ``` ```python Python theme={null} import requests def submit_kyc_document(document_id, value): url = f'https://api.sandbox.wepayout.com.br/v1/kyc/documents/{document_id}/update' headers = { 'Accept': 'application/json', 'Authorization': 'Bearer 123', 'Content-Type': 'application/json' } data = { 'value': value } response = requests.post(url, headers=headers, json=data) response.raise_for_status() return response.json() # Usage - Submit file URL file_result = submit_kyc_document(35, 'https://s3.amazonaws.com/bucket/file.pdf') print('File document submitted:', file_result) # Usage - Submit text value text_result = submit_kyc_document(36, 'John Doe') print('Text document submitted:', text_result) ``` ```json 200 OK theme={null} { "id": 5891, "status_id": 2, "status_name": "Waiting Approval Documents", "document_id": 35, "document_name": "kyc/qsa", "collection_name": null, "collection_id": null, "value_field": "https://s3.amazonaws.com/bucket-name/path/to/file", "rejection_reason": null, "label": "KYC/QSA", "type_field": "file", "required_field": true, "expires_at": null, "automaticatic_validation": 0 } ``` ## Best Practices > [!NOTE] > > **One Document at a Time**: Only one document can be updated per request. To submit multiple documents, make separate API calls for each. > [!WARNING] > > **File Extensions**: Ensure file-type documents use only supported extensions: `jpg`, `jpeg`, `gif`, `png`, or `pdf`. > [!TIP] > > **Document Status**: After submission, the document status will typically change to "Waiting Approval Documents" (status\_id: 2). ## Related Resources > [card] [List KYC](/api-reference/kyc/list-kyc) > > List all KYC verifications > [card] [Get KYC By ID](/api-reference/kyc/get) > > Get KYC by ID > [card] [Get KYC By Document](/api-reference/kyc/get-by-document) > > Get KYC by document number > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Create a payout payment # KYC Webhook Source: https://docs.wepayout.co/api-reference/kyc/webhook For each KYC status change, a webhook will be sent for the following statuses # KYC Webhook For each KYC status change, a webhook will be sent for the following statuses: ## Status Table | STATUS ID | STATUS NAME | | - | - | | 1 | Awaiting Upload Documents | | 2 | Awaiting Approval Documents | | 3 | Approved | | 4 | Pending Regularization | | 5 | Canceled | ## Configuring the callback URL Register the URL that receives the KYC webhooks for the `kyc` event, using the [Webhook Setup API](/api-reference/account/webhook/webhook-setup). You can [query](/api-reference/account/webhook/webhook-query), [update](/api-reference/account/webhook/webhook-update) and [remove](/api-reference/account/webhook/webhook-remove) it the same way. * The URL is registered per account: send `account_id` to register it for one of your subaccounts. The same URL can also receive other events — send `kyc` in the `events` list together with them. * Register a `secret` to receive the [HMAC-SHA256 signature](/concepts/webhooks#hmac-sha256-signature) in every KYC webhook. * A subaccount without its own `kyc` webhook receives its KYC webhooks on its main account's `kyc` webhook. See [Subaccounts without a webhook](/api-reference/account/webhook/webhook-setup#subaccounts-without-a-webhook). * When neither the account nor its main account has a `kyc` webhook registered, KYC webhooks keep being delivered to the callback URL previously configured by our Customer Experience team, if any, without the `x-webhook-wp-*` headers. > [!WARNING] > > Registering, updating or removing a webhook may take up to **5 minutes** to take effect. Until then, webhooks keep being delivered to the previous destination. ## Example Payload The webhook payload contains information about the KYC status change: ```json theme={null} { "entity": "KYC", "id": 1670, "merchant_id": 516, "status": { "id": 1, "name": "Awaiting Upload Documents" }, "metadata": { "blocked_person": { "name": "Test Kyc", "document": "99999919999979" } }, "updated_at": "2025-07-13T14:00:13.6090002" } ``` ## Example Headers The webhook request includes the following headers: ```json theme={null} { "Accept": "application/json", "Content-type": "application/json", "User-Agent": "WEpayments" } ``` When a webhook is registered for the `kyc` event, the request also includes the `x-webhook-wp-type` and `x-webhook-wp-timestamp` headers, plus `x-webhook-wp-signature` when a `secret` is set: ```json theme={null} { "Accept": "application/json", "Content-type": "application/json", "User-Agent": "WEpayments", "x-webhook-wp-type": "kyc", "x-webhook-wp-timestamp": "1790000000", "x-webhook-wp-signature": "5d41402abc4b2a76b9719d911017c592a3e1f5b8c4d6e7f8091a2b3c4d5e6f70" } ``` See [Webhook Signature](/concepts/webhooks) to verify the signature. ## Field Types **id** `integer` Unique identifier for the KYC record. **merchant\_id** `integer` Merchant identifier associated with the KYC. **status** `object` Object containing the current status of the KYC. **Status Object** **id** `integer` Status identifier. Possible values: `1`, `2`, `3`, `4`, `5` **name** `string` Name of the status. Possible values: `Awaiting Upload Documents`, `Awaiting Approval Documents`, `Approved`, `Pending Regularization`, `Canceled` **metadata** `object` Additional metadata about the KYC process. **Metadata Object** **blocked\_person** `object` Information about the person or entity in the KYC process. **Blocked Person Object** **name** `string` Name of the person or entity. **document** `string` Document number (CPF or CNPJ). **updated\_at** `string` Timestamp of when the KYC status was updated. Format: `` ## Webhook Status Flow ```mermaid theme={null} graph TD A[KYC Created] --> B[1 - Awaiting Upload Documents] B -->|Documents Uploaded| C[2 - Awaiting Approval Documents] C -->|Review Complete| D{Approved?} D -->|Yes| E[3 - Approved] D -->|Issues Found| F[4 - Pending Regularization] F -->|Regularized| C B -->|Canceled| G[5 - Canceled] C -->|Canceled| G B -.->|Webhook Sent| H[Your Server] C -.->|Webhook Sent| H E -.->|Webhook Sent| H F -.->|Webhook Sent| H G -.->|Webhook Sent| H ``` ## Related Resources > [card] [List KYC](/api-reference/kyc/list-kyc) > > List all KYC verifications > [card] [Get KYC By ID](/api-reference/kyc/get) > > Get KYC by ID > [card] [Get KYC By Document](/api-reference/kyc/get-by-document) > > Get KYC by document > [card] [Webhooks Guide](/concepts/webhooks) > > Learn about webhooks # Create Merchant Markup Configuration Source: https://docs.wepayout.co/api-reference/markup/account/create-merchant-markup POST https://api.sandbox.wepayout.com.br/v2/account/markup Create markup configuration for a merchant by product and payment method. Use this endpoint to configure markup rules for a merchant, defining how much additional amount will be charged per product and payment method. ## Request Body **account\_id** `integer` *required* ID of the merchant that will receive the markup. **parent\_id** `integer` Optional parent relationship ID. Can be used to associate this markup to a parent account or hierarchy level. **product** `string` *required* Product where the markup will be applied. Allowed values: `payin`, `payout` **payment\_method** `string` *required* Payment method where the markup will be applied. Allowed values: `pix`, `billet`, `credit_card` **type** `string` *required* Markup scope type. Currently, only `global` is supported externally. **mode** `string` *required* Type of markup to be applied. Allowed values: * `fixed`: fixed amount per charge * `percent`: percentage over the charge amount **amount** `number` *required* Markup value to be applied. Constraints: * Must be greater than or equal to `0.01`. **min\_charge\_value** `number` Minimum markup amount when mode is `percent`. Business rules: * **Required** when `mode` = `percent` * **Prohibited** when `mode` = `fixed` * Must be greater than or equal to `0.01` **max\_charge\_value** `number` Maximum markup amount when mode is `percent`. Business rules: * **Optional** * Must be greater than or equal to `min_charge_value` * **Prohibited** when `mode` = `fixed` > [!WARNING] > > When `mode` is `fixed`, do **not** send `min_charge_value` or `max_charge_value`. ## Request Examples ```json Percent markup example theme={null} { "account_id": 123, "product": "payin", "payment_method": "pix", "type": "global", "mode": "percent", "amount": 2.5, "min_charge_value": 1.0, "max_charge_value": 100.0 } ``` ```json Fixed markup example theme={null} { "account_id": 123, "product": "payout", "payment_method": "pix", "type": "global", "mode": "fixed", "amount": 5.0 } ``` ```bash cURL theme={null} curl -X POST "https://api.sandbox.wepayout.com.br/v2/account/markup" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "account_id": 123, "product": "payin", "payment_method": "pix", "type": "global", "mode": "percent", "amount": 2.5, "min_charge_value": 1.0, "max_charge_value": 100.0 }' ``` ## Response **id** `integer` Markup configuration ID. **product** `string` Product where the markup is applied. **payment\_method** `string` Payment method where the markup is applied. **account\_id** `integer` Merchant ID that receives the markup. **parent\_id** `integer or null` Parent relationship ID, when applicable. **type** `string` Markup scope type. Example: `global`. **mode** `string` Markup mode. Example: `fixed` or `percent`. **amount** `number` Markup value configured for this rule. **min\_charge\_value** `number or null` Minimum markup value when `mode` is `percent`. **max\_charge\_value** `number or null` Maximum markup value when `mode` is `percent`. ```json 201 Created theme={null} { "id": 1, "product": "payin", "payment_method": "pix", "account_id": 123, "parent_id": null, "type": "global", "mode": "percent", "amount": 2.5, "min_charge_value": 1.0, "max_charge_value": 100.0, "enabled": true, "created_at": "2024-06-01T12:00:00Z", "updated_at": "2024-06-01T12:00:00Z" } ``` ```json 422 Unprocessable Entity theme={null} { "message": "Dados inválidos.", "errors": { "product": [ "O campo product é inválido." ], "amount": [ "O campo amount é obrigatório." ], "min_charge_value": [ "O campo min_charge_value é obrigatório quando mode é percent." ] } } ``` ```json 500 Internal Server Error theme={null} { "error": "Não foi possível criar o markup." } ``` ## Related Resources > [card] [Update Merchant Markup](/api-reference/markup/account/update-merchant-markup) > > Update existing markup configurations > [card] [List Merchant Markups](/api-reference/markup/account/list-merchant-markups) > > View all markup configurations > [card] [About Markup](/markup/about-markup) > > Learn about markup types and configuration levels > [card] [Create Payin with Global Markup](/api-reference/markup/payin/create-payin-with-global-markup) > > Use global markup when creating payin charges # List Merchant Markups Configuration Source: https://docs.wepayout.co/api-reference/markup/account/list-merchant-markups GET https://api.sandbox.wepayout.com.br/v2/account/markups List markup configurations for merchants with optional filters. # List Merchant Markups Configuration Use this endpoint to list existing markup configurations for merchants. If no filters are provided, the API returns the markups that belong to the authenticated user's companies. ## Query Parameters **account\_id** `integer` Merchant ID filter. Business rules: * Optional * Must be greater than or equal to `1` **parent\_id** `integer` Parent merchant ID filter. Business rules: * Optional * Must be greater than or equal to `1` * **Prohibited** when `account_id` is present (one or the other) **id** `integer` Specific markup ID filter. Business rules: * Optional * Must be greater than or equal to `1` **payment\_method** `string` Filter by payment method. Allowed values: `pix`, `billet`, `credit_card` **product** `string` Filter by product. Allowed values: `payin`, `payout` **type** `string` Filter by markup type. Business rules: * Optional * Currently, only `global` is supported externally ## Request Examples ```bash cURL - List all markups for authenticated user theme={null} curl -X GET "https://api.sandbox.wepayout.com.br/v2/account/markups" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Accept: application/json" ``` ```bash cURL - Filter by account, product, payment_method and type theme={null} curl -X GET "https://api.sandbox.wepayout.com.br/v2/account/markups?account_id=123&product=payin&payment_method=pix&type=global" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Accept: application/json" ``` ```bash cURL - Fetch specific markup by id theme={null} curl -X GET "https://api.sandbox.wepayout.com.br/v2/account/markups?id=10" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Accept: application/json" ``` ```bash cURL - Invalid filters (account_id + parent_id and invalid payment_method) theme={null} curl -X GET "https://api.sandbox.wepayout.com.br/v2/account/markups?account_id=123&parent_id=456&payment_method=xyz" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Accept: application/json" ``` ```bash cURL - Internal error example theme={null} curl -X GET "https://api.sandbox.wepayout.com.br/v2/account/markups?account_id=123" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Accept: application/json" ``` ## Response **data** `array[object]` List of markup configurations. **Markup Object** **id** `integer` Markup configuration ID. **product** `string` Product where the markup is applied. **payment\_method** `string` Payment method where the markup is applied. **account\_id** `integer` Merchant ID that receives the markup. **parent\_id** `integer or null` Parent relationship ID, when applicable. **type** `string` Markup scope type. Example: `global`. **mode** `string` Markup mode. Example: `fixed` or `percent`. **amount** `number` Markup value configured for this rule. **min\_charge\_value** `number or null` Minimum markup value when `mode` is `percent`. **max\_charge\_value** `number or null` Maximum markup value when `mode` is `percent`. **enabled** `boolean` Indicates whether the markup configuration is currently active. **created\_at** `string` Date and time when the markup configuration was created. **updated\_at** `string` Date and time when the markup configuration was last updated. ```json 200 OK theme={null} { "data": [ { "id": 1, "product": "payin", "payment_method": "pix", "account_id": 123, "parent_id": null, "type": "global", "mode": "percent", "amount": 2.5, "min_charge_value": 1.0, "max_charge_value": 100.0, "enabled": true, "created_at": "2025-01-01 12:00:00", "updated_at": "2025-01-10 09:30:00" }, { "id": 2, "product": "payout", "payment_method": "ted", "account_id": 123, "parent_id": null, "type": "global", "mode": "fixed", "amount": 5.0, "min_charge_value": null, "max_charge_value": null, "enabled": true, "created_at": "2025-01-02 12:00:00", "updated_at": "2025-01-10 09:40:00" } ] } ``` ```json 422 Unprocessable Entity theme={null} { "message": "Dados inválidos.", "errors": { "parent_id": [ "O campo parent_id é proibido quando account_id está presente." ], "payment_method": [ "O campo payment_method é inválido." ] } } ``` ```json 500 Internal Server Error theme={null} { "error": "Não foi possível buscar os markups." } ``` ## Related Resources > [card] [Create Merchant Markup](/api-reference/markup/account/create-merchant-markup) > > Create new markup configurations > [card] [Update Merchant Markup](/api-reference/markup/account/update-merchant-markup) > > Update existing markup configurations > [card] [About Markup](/markup/about-markup) > > Learn about markup types and configuration levels > [card] [Create Payin with Global Markup](/api-reference/markup/payin/create-payin-with-global-markup) > > Use global markup when creating payin charges # Update Merchant Markup Configuration Source: https://docs.wepayout.co/api-reference/markup/account/update-merchant-markup PATCH https://api.sandbox.wepayout.com.br/v2/account/markup/{markupId} Update markup configuration for a merchant by markup ID. # Update Merchant Markup Configuration Use this endpoint to update an existing markup configuration for a merchant, identified by its `markupId`. ## Path Parameters **markupId** `integer` *required* Unique identifier of the markup configuration to be updated. ## Request Body **mode** `string` Markup mode to be applied. Allowed values: * `fixed` * `percent` Business rules: * **Required** if you send any of these fields: `amount`, `min_charge_value`, `max_charge_value`. **amount** `number` Markup value to be applied. Constraints: * Optional * Must be greater than or equal to `0.01` **min\_charge\_value** `number` Minimum markup amount when mode is `percent`. Business rules: * **Required** when `mode` = `percent` * **Prohibited** when `mode` = `fixed` * Must be greater than or equal to `0.01` **max\_charge\_value** `number` Maximum markup amount when mode is `percent`. Business rules: * Optional * Must be greater than or equal to `min_charge_value` * **Prohibited** when `mode` = `fixed` **enabled** `boolean` Flag to enable or disable this markup configuration. * Optional * Allowed values: `true`, `false` > [!WARNING] > > **Mode and range rules** > > * If you send any of `amount`, `min_charge_value` or `max_charge_value`, you **must** also send `mode`. > * When `mode = fixed`, you **must not** send `min_charge_value` or `max_charge_value`. > * When `mode = percent`, you **must** send `min_charge_value`, and `max_charge_value` is optional but must be greater than or equal to `min_charge_value` when provided. > [!NOTE] > > **Special rule when changing mode** > > If you change the mode from `percent` to `fixed`, the service will internally reset: > > * `min_charge_value = null` > * `max_charge_value = null` ## Request Examples ```bash cURL - Update to fixed mode and disable markup theme={null} curl -X PATCH "https://api.sandbox.wepayout.com.br/v2/account/markup/1234" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Content-Type: application/json" \ -d '{ "mode": "fixed", "amount": 10.0, "enabled": false }' ``` ```bash cURL - Invalid percent mode payload (missing min_charge_value) theme={null} curl -X PATCH "https://api.sandbox.wepayout.com.br/v2/account/markup/1234" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Content-Type: application/json" \ -d '{ "mode": "percent", "amount": 2.5 }' ``` ```bash cURL - Disable markup only theme={null} curl -X PATCH "https://api.sandbox.wepayout.com.br/v2/account/markup/1234" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Content-Type: application/json" \ -d '{ "enabled": false }' ``` ## Response **id** `integer` Markup configuration ID. **product** `string` Product where the markup is applied (e.g., `payin`). **payment\_method** `string` Payment method where the markup is applied (e.g., `pix`). **account\_id** `integer` Merchant ID that receives the markup. **parent\_id** `integer or null` Parent relationship ID, when applicable. **type** `string` Markup scope type. Example: `global`. **mode** `string` Markup mode. Example: `fixed` or `percent`. **amount** `number` Markup value configured for this rule. **min\_charge\_value** `number or null` Minimum markup value when `mode` is `percent`. **max\_charge\_value** `number or null` Maximum markup value when `mode` is `percent`. **enabled** `boolean` Indicates whether the markup configuration is currently active. **created\_at** `string` Date and time when the markup configuration was created. **updated\_at** `string` Date and time when the markup configuration was last updated. ```json 200 OK theme={null} { "id": 1234, "product": "payin", "payment_method": "pix", "account_id": 987, "parent_id": null, "type": "global", "mode": "fixed", "amount": 10.0, "min_charge_value": null, "max_charge_value": null, "enabled": false, "created_at": "2025-01-01 12:00:00", "updated_at": "2025-01-10 09:30:00" } ``` ```json 422 Unprocessable Entity theme={null} { "message": "Dados inválidos.", "errors": { "min_charge_value": [ "O campo min_charge_value é obrigatório quando mode é percent." ] } } ``` ## Related Resources > [card] [Create Merchant Markup](/api-reference/markup/account/create-merchant-markup) > > Create new markup configurations > [card] [List Merchant Markups](/api-reference/markup/account/list-merchant-markups) > > View all markup configurations > [card] [About Markup](/markup/about-markup) > > Learn about markup types and configuration levels > [card] [Create Payin with Global Markup](/api-reference/markup/payin/create-payin-with-global-markup) > > Use global markup when creating payin charges # Create Payin with Global Markup Source: https://docs.wepayout.co/api-reference/markup/payin/create-payin-with-global-markup POST https://api.sandbox.wepayout.com.br/v2/payin/payments Create a payin charge using global markup configuration. # Create Payin with Global Markup When creating a payin charge, you can use the **global markup** configuration that has been set up for your merchant. With global markup, you **do not need to send** the `markup` object in the request payload. > [!NOTE] > > **Global markup is applied automatically**: If the merchant has the markup feature enabled (`enable_markup = true`), the system will automatically search for and apply the submerchant's own markup or, if there is none, the global markup configuration. ## How It Works 1. **Validation**: The system checks if the `enable_markup` flag is active for the submerchant. 2. **Markup Search**: If enabled, the system automatically searches for a markup configuration, first for the submerchant and then for the merchant, based on: * `account_id` (submerchant ID) * `product` (payin) * `payment_method` (pix, boleto, etc.) 3. **Application**: If the submerchant has its own markup for the payment method, it is applied to the charge. Otherwise, the global markup is applied. 4. **Priority**: If you send an inline `markup` object, it takes precedence over the submerchant and global markups. ## Request Examples ```json PIX with Global Markup theme={null} { "payment_method": "pix", "invoice": "YOUR-CODE1234", "currency": "BRL", "amount": 10000, "country": "BR", "buyer": { "name": "Buyer Name", "document": { "type": "CPF", "number": "34960826312" }, "email": "buyer-email@wepayments.com.br" }, "pix": { "expire_date": "2025-12-31T23:59:59" } } ``` ```json Boleto with Global Markup theme={null} { "payment_method": "boleto", "invoice": "YOUR-INVOICE-CODE", "currency": "BRL", "amount": 50000, "country": "BR", "buyer": { "name": "Buyer Name", "email": "buyer@example.com", "document": { "type": "CPF", "number": "12345678901" }, "address": { "street": "Street Name", "number": "123", "complement": "Apt 456", "zipcode": "12345000", "city": "City Name", "district": "District Name", "state_code": "SP" } }, "originator_legal_entity": { "name": "Company Name", "document": "12345678901", "helpdesk": "company.com" }, "boleto": { "expire_date": "2025-12-31" } } ``` ```bash cURL - PIX with Global Markup theme={null} curl -X POST "https://api.sandbox.wepayout.com.br/v2/payin/payments" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Content-Type: application/json" \ -d '{ "payment_method": "pix", "invoice": "YOUR-CODE1234", "currency": "BRL", "amount": 10000, "country": "BR", "buyer": { "name": "Buyer Name", "document": { "type": "CPF", "number": "34960826312" }, "email": "buyer-email@wepayments.com.br" }, "pix": { "expire_date": "2025-12-31T23:59:59" } }' ``` ## Response **id** `integer` WEpayment's auto generated id, use this id to perform conciliation or perform queries via API / Dashboard. **merchant** `object` Merchant object. **Merchant** **id** `integer` Id of the WE account that created the payin. **name** `string` Name of the WE account that created the payin. **hash** `string` WEpayments auto generated hash, use this hash to send your user to the payment page. **payment\_page** `string` The WEpayments payment page is the place where you will redirect the end customer to pay the bill. **invoice** `string` Your identification number. **payment\_method** `string` Payment method that will be used in payin. Values: `pix`, `boleto` **amount** `integer` The payin total amount in cents. **currency** `object` Currency object. **Currency** **id** `integer` Currency id. **code** `string` Currency code (ISO 4217). **status** `string` Current status of the payin. Example: `pending` **markup** `object` Markup configuration applied to this charge (submerchant or global). **Markup Object** **mode** `string` Markup mode applied. Values: `fixed`, `percent` **amount** `number` Markup value configured for this charge. **min\_charge\_value** `number or null` Minimum markup value when `mode` is `percent`. Will be `null` when `mode` is `fixed`. **max\_charge\_value** `number or null` Maximum markup value when `mode` is `percent`. Will be `null` when `mode` is `fixed` or when not specified. **origin** `string or null` Level of the markup that was applied. Values: `sub_merchant`, `global` ```json 201 Created - PIX Charge with Global Markup theme={null} { "id": 51687, "merchant": { "id": 477, "name": "Merchant Name" }, "hash": "abc123def456", "payment_page": "https://payment.wepayments.com.br/abc123def456", "invoice": "YOUR-CODE1234", "payment_method": "pix", "amount": 10000, "currency": { "id": 1, "code": "BRL" }, "status": "pending", "markup": { "mode": "percent", "amount": 2.5, "min_charge_value": 0.50, "max_charge_value": 10.00, "origin": "sub_merchant" } } ``` ```json 422 Unprocessable Entity - Markup Required theme={null} { "status": false, "message": "Validation error", "data": { "markup": [ "O campo markup é obrigatório." ] } } ``` ```json 422 Unprocessable Entity - Error Verifying Markup theme={null} { "message": "Os dados fornecidos são inválidos.", "errors": { "markup": [ "Error verifying markup configuration. Please try again or contact support." ] } } ``` ```json 500 Internal Server Error theme={null} { "error": "Internal server error" } ``` ## Business Rules > [!WARNING] > > **Markup Required**: If `enable_markup = true` for the submerchant and there is neither a submerchant markup nor a global markup configuration for the payment method, you must send an inline `markup` object. Otherwise, the request will fail with a 422 error. > [!NOTE] > > **Automatic Application**: When `enable_markup = true` and a submerchant or global markup exists, it is automatically applied without requiring the `markup` object in the request. ## Error Scenarios ### Scenario 1: enable\_markup = true, No Submerchant or Global Markup, No Inline Markup If the submerchant has `enable_markup = true` but: * No submerchant markup configuration exists for the payment method * No global markup configuration exists for the payment method * No inline markup object is sent in the request **Result**: Returns 422 error with message "O campo markup é obrigatório." ### Scenario 2: Error Verifying Global Markup If there is an error while searching for or verifying the global markup configuration. **Result**: Returns 422 error with message "Error verifying markup configuration. Please try again or contact support." ## Related Resources > [card] [Create Payin with Inline Markup](/api-reference/markup/payin/create-payin-with-inline-markup) > > Learn how to create payin with inline markup > [card] [Create Merchant Markup](/api-reference/markup/account/create-merchant-markup) > > Configure global markup for merchants > [card] [About Markup](/markup/about-markup) > > Understand markup types and configuration levels > [card] [Create Charge](/api-reference/cash-in/payin/create-charge) > > Complete documentation for creating payin charges # Create Payin with Inline Markup Source: https://docs.wepayout.co/api-reference/markup/payin/create-payin-with-inline-markup POST https://api.sandbox.wepayout.com.br/v2/payin/payments Create a payin charge with inline markup configuration. # Create Payin with Inline Markup When creating a payin charge, you can include an `inline markup` object in the request payload. > [!NOTE] > > **Inline markup takes precedence**: If you send a `markup` object in the charge creation request, it will override any global or submerchant markup configurations. ## Markup Object Structure The `markup` object should be added to the request body when creating a charge via `POST /v2/payin/payments`. **markup** `object` Optional inline markup configuration for this specific charge. **Markup Object** **mode** `string` *required* How the markup value will be applied. Allowed values: * `fixed`: fixed amount per charge * `percent`: percentage over the charge amount **amount** `number` *required* Markup value to be applied. Constraints: * Must be greater than or equal to `0.01` **min\_charge\_value** `number` Minimum markup amount when mode is `percent`. Business rules: * **Required** when `mode` = `percent` * **Prohibited** when `mode` = `fixed` * Must be greater than or equal to `0.01` **max\_charge\_value** `number` Maximum markup amount when mode is `percent`. Business rules: * **Optional** * Must be greater than or equal to `min_charge_value` * **Prohibited** when `mode` = `fixed` > [!WARNING] > > When `mode` is `fixed`, do **not** send `min_charge_value` or `max_charge_value`. ## Request Examples ```json PIX with Percent Markup theme={null} { "payment_method": "pix", "invoice": "YOUR-CODE1234", "currency": "BRL", "amount": 10000, "country": "BR", "buyer": { "name": "Buyer Name", "document": { "type": "CPF", "number": "34960826312" }, "email": "buyer-email@wepayments.com.br" }, "pix": { "expire_date": "2025-12-31T23:59:59" }, "markup": { "mode": "percent", "amount": 2.5, "min_charge_value": 0.50, "max_charge_value": 10.00 } } ``` ```json PIX with Fixed Markup theme={null} { "payment_method": "pix", "invoice": "YOUR-CODE1234", "currency": "BRL", "amount": 10000, "country": "BR", "buyer": { "name": "Buyer Name", "document": { "type": "CPF", "number": "34960826312" }, "email": "buyer-email@wepayments.com.br" }, "pix": { "expire_date": "2025-12-31T23:59:59" }, "markup": { "mode": "fixed", "amount": 5.0 } } ``` ```json Boleto with Percent Markup theme={null} { "payment_method": "boleto", "invoice": "YOUR-INVOICE-CODE", "currency": "BRL", "amount": 50000, "country": "BR", "buyer": { "name": "Buyer Name", "email": "buyer@example.com", "document": { "type": "CPF", "number": "12345678901" }, "address": { "street": "Street Name", "number": "123", "complement": "Apt 456", "zipcode": "12345000", "city": "City Name", "district": "District Name", "state_code": "SP" } }, "originator_legal_entity": { "name": "Company Name", "document": "12345678901", "helpdesk": "company.com" }, "boleto": { "expire_date": "2025-12-31" }, "markup": { "mode": "percent", "amount": 2.5, "min_charge_value": 0.50, "max_charge_value": 10.00 } } ``` ```bash cURL - PIX with Percent Markup theme={null} curl -X POST "https://api.sandbox.wepayout.com.br/v2/payin/payments" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Content-Type: application/json" \ -d '{ "payment_method": "pix", "invoice": "YOUR-CODE1234", "currency": "BRL", "amount": 10000, "country": "BR", "buyer": { "name": "Buyer Name", "document": { "type": "CPF", "number": "34960826312" }, "email": "buyer-email@wepayments.com.br" }, "pix": { "expire_date": "2025-12-31T23:59:59" }, "markup": { "mode": "percent", "amount": 2.5, "min_charge_value": 0.50, "max_charge_value": 10.00 } }' ``` ```bash cURL - PIX with Fixed Markup theme={null} curl -X POST "https://api.sandbox.wepayout.com.br/v2/payin/payments" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Content-Type: application/json" \ -d '{ "payment_method": "pix", "invoice": "YOUR-CODE1234", "currency": "BRL", "amount": 10000, "country": "BR", "buyer": { "name": "Buyer Name", "document": { "type": "CPF", "number": "34960826312" }, "email": "buyer-email@wepayments.com.br" }, "pix": { "expire_date": "2025-12-31T23:59:59" }, "markup": { "mode": "fixed", "amount": 5.0 } }' ``` ```bash cURL - Boleto with Percent Markup theme={null} curl -X POST "https://api.sandbox.wepayout.com.br/v2/payin/payments" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Content-Type: application/json" \ -d '{ "payment_method": "boleto", "invoice": "YOUR-INVOICE-CODE", "currency": "BRL", "amount": 50000, "country": "BR", "buyer": { "name": "Buyer Name", "email": "buyer@example.com", "document": { "type": "CPF", "number": "12345678901" }, "address": { "street": "Street Name", "number": "123", "complement": "Apt 456", "zipcode": "12345000", "city": "City Name", "district": "District Name", "state_code": "SP" } }, "originator_legal_entity": { "name": "Company Name", "document": "12345678901", "helpdesk": "company.com" }, "boleto": { "expire_date": "2025-12-31" }, "markup": { "mode": "percent", "amount": 2.5, "min_charge_value": 0.50, "max_charge_value": 10.00 } }' ``` ## Response **id** `integer` WEpayment's auto generated id, use this id to perform conciliation or perform queries via API / Dashboard. **merchant** `object` Merchant object. **Merchant** **id** `integer` Id of the WE account that created the payin. **name** `string` Name of the WE account that created the payin. **hash** `string` WEpayments auto generated hash, use this hash to send your user to the payment page. **payment\_page** `string` The WEpayments payment page is the place where you will redirect the end customer to pay the bill. **invoice** `string` Your identification number. **payment\_method** `string` Payment method that will be used in payin. Values: `pix`, `boleto` **amount** `integer` The payin total amount in cents. **currency** `object` Currency object. **Currency** **id** `integer` Currency id. **code** `string` Currency code (ISO 4217). **status** `string` Current status of the payin. Example: `pending` **markup** `object` Inline markup configuration applied to this charge. **Markup Object** **mode** `string` Markup mode applied. Values: `fixed`, `percent` **amount** `number` Markup value configured for this charge. **min\_charge\_value** `number or null` Minimum markup value when `mode` is `percent`. Will be `null` when `mode` is `fixed`. **max\_charge\_value** `number or null` Maximum markup value when `mode` is `percent`. Will be `null` when `mode` is `fixed` or when not specified. **origin** `string` Level of the markup that was applied. Always `inline` when the `markup` object is sent in the request. Any `origin` sent in the request is ignored. Values: `inline` ```json 201 Created - PIX Charge with Markup theme={null} { "id": 51687, "merchant": { "id": 477, "name": "Merchant Name" }, "hash": "abc123def456", "payment_page": "https://payment.wepayments.com.br/abc123def456", "invoice": "YOUR-CODE1234", "payment_method": "pix", "amount": 10000, "currency": { "id": 1, "code": "BRL" }, "status": "pending", "markup": { "mode": "percent", "amount": 2.5, "min_charge_value": 0.50, "max_charge_value": 10.00, "origin": "inline" } } ``` ```json 422 Unprocessable Entity - Invalid markup.mode theme={null} { "message": "Os dados fornecidos são inválidos.", "errors": { "markup.mode": [ "The markup.mode field is invalid" ] } } ``` ```json 422 Unprocessable Entity - Invalid markup.amount theme={null} { "message": "Os dados fornecidos são inválidos.", "errors": { "markup.amount": [ "The markup.amount must be at least 0.01" ] } } ``` ```json 500 Internal Server Error theme={null} { "error": "Internal server error" } ``` ## How It Works 1. **Priority**: The inline markup configuration takes precedence over global and submerchant markup settings. 2. **Calculation** (for percent mode): * The system converts the markup amount to percentage: `amount * 100 = percentage%` * Then calculates: `transaction_amount * (amount)` * If calculated value \< `min_charge_value` → applies `min_charge_value` * If calculated value > `max_charge_value` → applies `max_charge_value` * Otherwise → applies the calculated value 3. **Fixed Mode**: When using `fixed` mode, the markup amount is applied directly regardless of the transaction value. ## Related Resources > [card] [Create Charge](/api-reference/cash-in/payin/create-charge) > > Complete documentation for creating payin charges > [card] [About Markup](/markup/about-markup) > > Learn about markup types and configuration levels # Create Payout with Global Markup Source: https://docs.wepayout.co/api-reference/markup/payout/create-payout-with-global-markup POST https://api.sandbox.wepayout.com.br/v2/payout/payments Create a payout payment using global markup configuration. # Create Payout with Global Markup When creating a payout payment, you can use the **global markup** configuration that has been set up for your merchant. With global markup, you **do not need to send** the `markup` object in the request payload. > [!NOTE] > > **Global markup is applied automatically**: If the merchant has the markup feature enabled (`enable_markup = true`), the system will automatically search for and apply the submerchant's own markup or, if there is none, the global markup configuration. ## How It Works 1. **Validation**: The system checks if the `enable_markup` flag is active for the submerchant. 2. **Markup Search**: If enabled, the system automatically searches for a markup configuration, first for the submerchant and then for the merchant, based on: * `account_id` (submerchant ID) * `product` (payout) * `payment_method` (markup for payout is currently available for PIX only) 3. **Application**: If the submerchant has its own markup for the payment method, it is applied to the payment. Otherwise, the global markup is applied. 4. **Priority**: If you send an inline `markup` object, it takes precedence over the submerchant and global markups. ## Request Examples ```json PIX with Global Markup theme={null} { "payment_method": "PIX", "invoice": "e3317882-f821-455b-b082-dc3ba36e8a57", "currency": "BRL", "amount": 100.50, "country": "BR", "beneficiary": { "name": "John Doe", "document": { "type": "CPF", "number": "12345678901" }, "pix": { "key": "12345678901" } } } ``` ```bash cURL - PIX with Global Markup theme={null} curl -X POST "https://api.sandbox.wepayout.com.br/v2/payout/payments" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Content-Type: application/json" \ -d '{ "payment_method": "PIX", "invoice": "e3317882-f821-455b-b082-dc3ba36e8a57", "currency": "BRL", "amount": 100.50, "country": "BR", "beneficiary": { "name": "John Doe", "document": { "type": "CPF", "number": "12345678901" }, "pix": { "key": "12345678901" } } }' ``` ## Response **id** `integer` WEpayment's auto generated id, use this id to perform conciliation or perform queries via API / Dashboard. **merchant** `object` Merchant object. **Merchant** **id** `integer` Id of the WE account that created the payout. **name** `string` Name of the WE account that created the payout. **payment\_method** `string` Payment method used for the payout. Values: `PIX` **amount** `string` The payout amount formatted with currency symbol. **currency** `string` Currency code (ISO 4217). **invoice** `string` Invoice identifier. **status** `object` Payout status. **Status** **id** `integer` Status ID. **name** `string` Status name (e.g., "Awaiting"). **beneficiary** `object` Beneficiary information. **Beneficiary** **name** `string` Beneficiary name. **document** `object` Document information. **markup** `object or null` Markup configuration applied to this payment (submerchant or global). **Markup Object** **mode** `string` Markup mode applied. Values: `fixed`, `percent` **amount** `number` Markup value configured for this payment. **min\_charge\_value** `number or null` Minimum markup value when `mode` is `percent`. Will be `null` when `mode` is `fixed`. **max\_charge\_value** `number or null` Maximum markup value when `mode` is `percent`. Will be `null` when `mode` is `fixed` or when not specified. **origin** `string or null` Level of the markup that was applied. Values: `sub_merchant`, `global` ```json 201 Created - PIX Payment with Global Markup theme={null} { "id": 12345, "merchant": { "id": 477, "name": "Merchant Name" }, "payment_method": "PIX", "amount": "R$ 100,50", "currency": "BRL", "invoice": "e3317882-f821-455b-b082-dc3ba36e8a57", "status": { "id": 1, "name": "Awaiting" }, "beneficiary": { "name": "John Doe", "document": { "type": "CPF", "number": "12345678901" } }, "markup": null } ``` > [!NOTE] > > **Markup returns null**: It is normal for the `markup` field to return `null` when using global markup. ```json 422 Unprocessable Entity - Markup Required theme={null} { "message": "The given data was invalid", "errors": { "markup": [ "Inline markup is required when no global markup is configured" ] } } ``` ```json 500 Internal Server Error theme={null} { "error": "Internal server error" } ``` ## Business Rules > [!WARNING] > > **Markup Required**: If `enable_markup = true` for the submerchant and there is neither a submerchant markup nor a global markup configuration for the payment method, you must send an inline `markup` object. Otherwise, the request will fail with a 422 error. > [!NOTE] > > **Automatic Application**: When `enable_markup = true` and a submerchant or global markup exists, it is automatically applied without requiring the `markup` object in the request. ## Error Scenarios ### Scenario 1: enable\_markup = true, No Submerchant or Global Markup, No Inline Markup If the submerchant has `enable_markup = true` but: * No submerchant markup configuration exists for the payment method * No global markup configuration exists for the payment method * No inline markup object is sent in the request **Result**: Returns 422 error with message "O campo markup é obrigatório." ### Scenario 2: Error Verifying Global Markup If there is an error while searching for or verifying the global markup configuration. **Result**: Returns 422 error with message "Error verifying markup configuration. Please try again or contact support." ## Related Resources > [card] [Create Payout with Inline Markup](/api-reference/markup/payout/create-payout-with-inline-markup) > > Learn how to create payout with inline markup > [card] [Create Merchant Markup](/api-reference/markup/account/create-merchant-markup) > > Configure global markup for merchants > [card] [About Markup](/markup/about-markup) > > Understand markup types and configuration levels > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Complete documentation for creating payout payments # Create Payout with Inline Markup Source: https://docs.wepayout.co/api-reference/markup/payout/create-payout-with-inline-markup POST https://api.sandbox.wepayout.com.br/v2/payout/payments Create a payout payment with inline markup configuration. # Create Payout with Inline Markup When creating a payout payment, you can include an `inline markup` object in the request payload. > [!NOTE] > > **Inline markup takes precedence**: If you send a `markup` object in the payment creation request, it will override any global or submerchant markup configurations. ## Markup Object Structure The `markup` object should be added to the request body when creating a payment via `POST /v2/payout/payments`. **markup** `object` Optional inline markup configuration for this specific payment. **Markup Object** **mode** `string` *required* How the markup value will be applied. Allowed values: * `fixed`: fixed amount per payment * `percent`: percentage over the payment amount **amount** `number` *required* Markup value to be applied. Constraints: * Must be greater than or equal to `0.01` **min\_charge\_value** `number` Minimum markup amount when mode is `percent`. Business rules: * **Required** when `mode` = `percent` * **Prohibited** when `mode` = `fixed` * Must be greater than or equal to `0.01` **max\_charge\_value** `number` Maximum markup amount when mode is `percent`. Business rules: * **Optional** * Must be greater than or equal to `min_charge_value` * **Prohibited** when `mode` = `fixed` > [!WARNING] > > When `mode` is `fixed`, do **not** send `min_charge_value` or `max_charge_value`. ## Request Examples ```json PIX with Percent Markup theme={null} { "payment_method": "PIX", "invoice": "e3317882-f821-455b-b082-dc3ba36e8a57", "currency": "BRL", "amount": 100.50, "country": "BR", "beneficiary": { "name": "John Doe", "document": { "type": "CPF", "number": "12345678901" }, "pix": { "key": "12345678901" } }, "markup": { "mode": "percent", "amount": 2.5, "min_charge_value": 0.50, "max_charge_value": 10.00 } } ``` ```json PIX with Fixed Markup theme={null} { "payment_method": "PIX", "invoice": "e3317882-f821-455b-b082-dc3ba36e8a57", "currency": "BRL", "amount": 100.50, "country": "BR", "beneficiary": { "name": "John Doe", "document": { "type": "CPF", "number": "12345678901" }, "pix": { "key": "12345678901" } }, "markup": { "mode": "fixed", "amount": 5.0 } } ``` ```bash cURL - PIX with Percent Markup theme={null} curl -X POST "https://api.sandbox.wepayout.com.br/v2/payout/payments" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Content-Type: application/json" \ -d '{ "payment_method": "PIX", "invoice": "e3317882-f821-455b-b082-dc3ba36e8a57", "currency": "BRL", "amount": 100.50, "country": "BR", "beneficiary": { "name": "John Doe", "document": { "type": "CPF", "number": "12345678901" }, "pix": { "key": "12345678901", "key_type": "CPF" } }, "markup": { "mode": "percent", "amount": 2.5, "min_charge_value": 0.50, "max_charge_value": 10.00 } }' ``` ```bash cURL - PIX with Fixed Markup theme={null} curl -X POST "https://api.sandbox.wepayout.com.br/v2/payout/payments" \ -H "Authorization: Bearer YOUR_TOKEN_HERE" \ -H "Content-Type: application/json" \ -d '{ "payment_method": "PIX", "invoice": "e3317882-f821-455b-b082-dc3ba36e8a57", "currency": "BRL", "amount": 100.50, "country": "BR", "beneficiary": { "name": "John Doe", "document": { "type": "CPF", "number": "12345678901" }, "pix": { "key": "12345678901", "key_type": "CPF" } }, "markup": { "mode": "fixed", "amount": 5.0 } }' ``` ## Response **id** `integer` WEpayment's auto generated id, use this id to perform conciliation or perform queries via API / Dashboard. **merchant** `object` Merchant object. **Merchant** **id** `integer` Id of the WE account that created the payout. **name** `string` Name of the WE account that created the payout. **payment\_method** `string` Payment method used for the payout. Values: `PIX` **amount** `string` The payout amount formatted with currency symbol. **currency** `string` Currency code (ISO 4217). **invoice** `string` Invoice identifier. **status** `object` Payout status. **Status** **id** `integer` Status ID. **name** `string` Status name (e.g., "Awaiting"). **beneficiary** `object` Beneficiary information. **Beneficiary** **name** `string` Beneficiary name. **document** `object` Document information. **markup** `object` Inline markup configuration applied to this payment. **Markup Object** **mode** `string` Markup mode applied. Values: `fixed`, `percent` **amount** `number` Markup value configured for this payment. **min\_charge\_value** `number or null` Minimum markup value when `mode` is `percent`. Will be `null` when `mode` is `fixed`. **max\_charge\_value** `number or null` Maximum markup value when `mode` is `percent`. Will be `null` when `mode` is `fixed` or when not specified. **origin** `string` Level of the markup that was applied. Always `inline` when the `markup` object is sent in the request. Any `origin` sent in the request is ignored. Values: `inline` ```json 201 Created - PIX Payment with Markup theme={null} { "id": 12345, "merchant": { "id": 477, "name": "Merchant Name" }, "payment_method": "PIX", "amount": "R$ 100,50", "currency": "BRL", "invoice": "e3317882-f821-455b-b082-dc3ba36e8a57", "status": { "id": 1, "name": "Awaiting" }, "beneficiary": { "name": "John Doe", "document": { "type": "CPF", "number": "12345678901" } }, "markup": { "mode": "percent", "amount": 2.5, "min_charge_value": 0.50, "max_charge_value": 10.00, "origin": "inline" }, "purpose": null, "paid_at": null, "created_at": "2024-01-15T10:30:00.000000Z", "updated_at": "2024-01-15T10:30:00.000000Z" } ``` ```json 422 Unprocessable Entity - Markup Only for PIX theme={null} { "message": "The given data was invalid", "errors": { "markup": [ "Markup is only allowed for PIX payments" ] } } ``` ```json 422 Unprocessable Entity - Invalid markup.mode theme={null} { "message": "The given data was invalid", "errors": { "markup.mode": [ "The selected markup.mode is invalid." ] } } ``` ```json 422 Unprocessable Entity - Invalid markup.amount theme={null} { "message": "The given data was invalid", "errors": { "markup.amount": [ "The markup.amount must be at least 0.01." ] } } ``` ```json 422 Unprocessable Entity - Missing min_charge_value for percent mode theme={null} { "message": "The given data was invalid", "errors": { "markup.min_charge_value": [ "The markup.min_charge value field is required when markup.mode is percent." ] } } ``` ```json 422 Unprocessable Entity - Invalid charge values for fixed mode theme={null} { "message": "The given data was invalid", "errors": { "markup.min_charge_value": [ "Invalid charge values for fixed mode" ] } } ``` ```json 422 Unprocessable Entity - Markup Required theme={null} { "message": "The given data was invalid", "errors": { "markup": [ "Inline markup is required when no global markup is configured" ] } } ``` ```json 500 Internal Server Error theme={null} { "message": "Internal error" } ``` ## How It Works 1. **Priority**: The inline markup configuration takes precedence over global and submerchant markup settings. 2. **Calculation** (for percent mode): * The system calculates: `payment_amount * (amount / 100)` * If calculated value \< `min_charge_value` → applies `min_charge_value` * If calculated value > `max_charge_value` → applies `max_charge_value` * Otherwise → applies the calculated value 3. **Fixed Mode**: When using `fixed` mode, the markup amount is applied directly regardless of the transaction value. ## Related Resources > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Complete documentation for creating payout payments > [card] [About Markup](/markup/about-markup) > > Learn about markup types and configuration levels # Batch Apply Submerchant Markup Source: https://docs.wepayout.co/api-reference/markup/submerchant/batch-apply-submerchant-markup POST https://api.sandbox.wepayout.com.br/v2/account/{merchantId}/submerchants/markups/batch Apply the same markup configuration to many submerchants at once. # Batch Apply Submerchant Markup Use this endpoint to apply the same markup configuration to up to 500 submerchants in one request. Each submerchant is processed on its own. If one of them fails, the others are still saved, and the response reports the result for each submerchant. > [!WARNING] > > **The configuration is replaced for each submerchant.** Like [Configure Submerchant Markup](/api-reference/markup/submerchant/upsert-submerchant-markup), each listed submerchant keeps only the items sent in `markups`. Any product and payment method you leave out goes back to the global markup. ## Path Parameters **merchantId** `integer` *required* ID of the merchant (parent account). It must be one of the authenticated user's companies. ## Request Body **sub\_merchant\_ids** `array[integer]` *required* IDs of the submerchants that will receive the markup. Send between `1` and `500` IDs. Duplicate IDs are ignored. **markups** `array[object]` *required* Markup configurations to apply. Same fields and rules as the `markups` field of [Configure Submerchant Markup](/api-reference/markup/submerchant/upsert-submerchant-markup). ## Request Examples ```json Batch apply theme={null} { "sub_merchant_ids": [1234, 1235, 7777], "markups": [ { "product": "payin", "payment_method": "pix", "mode": "percent", "amount": 1.4, "min_charge_value": 1.0, "max_charge_value": 5.0 }, { "product": "payout", "payment_method": "pix", "mode": "fixed", "amount": 0.8 } ] } ``` ```bash cURL theme={null} curl -X POST "https://api.sandbox.wepayout.com.br/v2/account/123/submerchants/markups/batch" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "sub_merchant_ids": [1234, 1235], "markups": [ { "product": "payin", "payment_method": "pix", "mode": "fixed", "amount": 1.0 } ] }' ``` ## Response The response is `200 OK` even when some submerchants fail. Check `failed` and `results` to find them. **total** `integer` Number of submerchants processed. **succeeded** `integer` Number of submerchants saved. **failed** `integer` Number of submerchants that failed. **results** `array[object]` Result for each submerchant. **Result Object** **sub\_merchant\_id** `integer` Submerchant ID. **status** `string` Values: `success`, `failed`. **error\_code** `string or null` Reason for the failure. `null` on success. Values: * `sub_merchant_not_child`: the ID is not a submerchant of `merchantId` * `internal_error`: the markup could not be saved **message** `string or null` Description of the failure. `null` on success. ```json 200 OK theme={null} { "total": 3, "succeeded": 2, "failed": 1, "results": [ { "sub_merchant_id": 1234, "status": "success", "error_code": null, "message": null }, { "sub_merchant_id": 1235, "status": "success", "error_code": null, "message": null }, { "sub_merchant_id": 7777, "status": "failed", "error_code": "sub_merchant_not_child", "message": "The subaccount 7777 does not belong to this account." } ] } ``` ```json 422 Unprocessable Entity theme={null} { "message": "The given data was invalid.", "errors": { "sub_merchant_ids": [ "The batch exceeds the limit of 500 subaccounts." ], "markups.0.min_charge_value": [ "Minimum and maximum values are required when the mode is percent." ] } } ``` ```json 500 Internal Server Error theme={null} { "error": "Failed to apply the markups in batch." } ``` ## Related Resources > [card] [List Submerchant Markups](/api-reference/markup/submerchant/list-submerchant-markups) > > Find the submerchants to update > [card] [Configure Submerchant Markup](/api-reference/markup/submerchant/upsert-submerchant-markup) > > Set the markup of a single submerchant # Remove Submerchant Markup Source: https://docs.wepayout.co/api-reference/markup/submerchant/delete-submerchant-markup DELETE https://api.sandbox.wepayout.com.br/v2/account/{merchantId}/submerchants/{subMerchantId}/markups Remove the markup configuration of a submerchant. # Remove Submerchant Markup Use this endpoint to remove all of a submerchant's own markup configurations, for every product and payment method. > [!NOTE] > > After the removal, the submerchant's transactions use the merchant's **global markup** again. An inline `markup` sent in the request still takes priority. ## Path Parameters **merchantId** `integer` *required* ID of the merchant (parent account). It must be one of the authenticated user's companies. **subMerchantId** `integer` *required* ID of the submerchant. It must be a submerchant of `merchantId`. ## Request Example ```bash cURL theme={null} curl -X DELETE "https://api.sandbox.wepayout.com.br/v2/account/123/submerchants/1234/markups" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" ``` ## Response **message** `string` Confirmation message. **deleted** `integer` Number of markup configurations removed. ```json 200 OK theme={null} { "message": "Markup removed successfully.", "deleted": 3 } ``` ```json 404 Not Found theme={null} { "message": "Markup not found." } ``` ```json 422 Unprocessable Entity - Not a submerchant of this merchant theme={null} { "message": "The given data was invalid.", "errors": { "subMerchantId": [ "The subaccount 7777 does not belong to this account." ] } } ``` ```json 500 Internal Server Error theme={null} { "error": "Failed to remove markup." } ``` ## Related Resources > [card] [Configure Submerchant Markup](/api-reference/markup/submerchant/upsert-submerchant-markup) > > Set the markup of a submerchant > [card] [List Merchant Markups](/api-reference/markup/account/list-merchant-markups) > > View the global markup # Get Submerchant Markup Source: https://docs.wepayout.co/api-reference/markup/submerchant/get-submerchant-markup GET https://api.sandbox.wepayout.com.br/v2/account/{merchantId}/submerchants/{subMerchantId}/markups Get the markup configuration of a single submerchant. # Get Submerchant Markup Use this endpoint to get the markup configured for one submerchant, grouped by product (`payin` and `payout`). If the submerchant has no markup of its own, `has_markup` is `false` and the lists are empty. In that case the merchant's global markup is applied. ## Path Parameters **merchantId** `integer` *required* ID of the merchant (parent account). It must be one of the authenticated user's companies. **subMerchantId** `integer` *required* ID of the submerchant. It must be a submerchant of `merchantId`. ## Request Example ```bash cURL theme={null} curl -X GET "https://api.sandbox.wepayout.com.br/v2/account/123/submerchants/1234/markups" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" ``` ## Response The response is a submerchant object, with the same fields as an item of [List Submerchant Markups](/api-reference/markup/submerchant/list-submerchant-markups). **id** `integer` Submerchant ID. **name** `string` Submerchant name. **legal\_name** `string or null` Submerchant legal name. **document** `string or null` Submerchant document (CNPJ or CPF), digits only. **has\_markup** `boolean` `true` when the submerchant has its own markup for at least one product and payment method. **payin** `array[object]` Markups configured for `payin`. Each item has `id`, `payment_method`, `mode`, `amount`, `min_charge_value` and `max_charge_value`. Amounts are strings with 2 decimal places. **payout** `array[object]` Markups configured for `payout`, with the same structure as `payin`. **updated\_at** `string or null` Date and time of the most recent change to the submerchant's markup. `null` when there is no markup. ```json 200 OK theme={null} { "id": 1234, "name": "Store X", "legal_name": "Store X LTDA", "document": "12345678000190", "has_markup": true, "payin": [ { "id": 56, "payment_method": "billet", "mode": "fixed", "amount": "2.00", "min_charge_value": null, "max_charge_value": null }, { "id": 55, "payment_method": "pix", "mode": "percent", "amount": "1.40", "min_charge_value": "1.00", "max_charge_value": "5.00" } ], "payout": [ { "id": 57, "payment_method": "pix", "mode": "fixed", "amount": "0.80", "min_charge_value": null, "max_charge_value": null } ], "updated_at": "2026-09-28 10:49:13" } ``` ```json 422 Unprocessable Entity - Not a submerchant of this merchant theme={null} { "message": "The given data was invalid.", "errors": { "subMerchantId": [ "The subaccount 7777 does not belong to this account." ] } } ``` ```json 404 Not Found theme={null} { "message": "Subaccount not found." } ``` ```json 500 Internal Server Error theme={null} { "error": "Failed to find markup." } ``` ## Related Resources > [card] [Configure Submerchant Markup](/api-reference/markup/submerchant/upsert-submerchant-markup) > > Set the markup of a submerchant > [card] [Remove Submerchant Markup](/api-reference/markup/submerchant/delete-submerchant-markup) > > Go back to the global markup # List Submerchant Markups Source: https://docs.wepayout.co/api-reference/markup/submerchant/list-submerchant-markups GET https://api.sandbox.wepayout.com.br/v2/account/{merchantId}/submerchants/markups List the submerchants of a merchant with their own markup configuration. # List Submerchant Markups Use this endpoint to list the submerchants of a merchant, together with the markup configured for each one. Submerchants that do not have their own markup are also returned, with `has_markup: false` and empty `payin` and `payout` lists. These submerchants use the merchant's [global markup](/api-reference/markup/account/list-merchant-markups). ## Path Parameters **merchantId** `integer` *required* ID of the merchant (parent account). It must be one of the authenticated user's companies. ## Query Parameters **search** `string` Free-text filter. Matches the submerchant's name or legal name (partial match), ID (exact match), or document. When searching by document, punctuation is ignored, so `12.345.678/0001-90` and `12345678000190` are the same. Max length: `255` **page** `integer` (default: 1) Page number. Must be greater than or equal to `1`. **per\_page** `integer` (default: 10) Number of submerchants per page. Must be between `1` and `500`. ## Request Examples ```bash cURL - List submerchants theme={null} curl -X GET "https://api.sandbox.wepayout.com.br/v2/account/123/submerchants/markups?page=1&per_page=25" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" ``` ```bash cURL - Search by document theme={null} curl -X GET "https://api.sandbox.wepayout.com.br/v2/account/123/submerchants/markups?search=12.345.678/0001-90" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json" ``` ## Response **data** `array[object]` List of submerchants. **Submerchant Object** **id** `integer` Submerchant ID. **name** `string` Submerchant name. **legal\_name** `string or null` Submerchant legal name. **document** `string or null` Submerchant document (CNPJ or CPF), digits only. **has\_markup** `boolean` `true` when the submerchant has its own markup for at least one product and payment method. When `false`, the global markup is applied. **payin** `array[object]` Markups configured for `payin`, sorted by payment method. Empty when there is none. **Markup Object** **id** `integer` Markup configuration ID. **payment\_method** `string` Payment method. Values: `pix`, `billet`, `credit_card`. **mode** `string` Markup mode. Values: `fixed`, `percent`. **amount** `string` Markup value, with 2 decimal places. In BRL when `mode` is `fixed`, and a percentage when `mode` is `percent` (`"1.50"` means 1.5%). **min\_charge\_value** `string or null` Minimum markup amount in BRL when `mode` is `percent`. `null` when `mode` is `fixed`. **max\_charge\_value** `string or null` Maximum markup amount in BRL when `mode` is `percent`. `null` when `mode` is `fixed`. **payout** `array[object]` Markups configured for `payout`, with the same structure as `payin`. Payment method values: `pix`, `ted`. **updated\_at** `string or null` Date and time (`Y-m-d H:i:s`, America/Sao\_Paulo) of the most recent change to the submerchant's markup. `null` when there is no markup. **total** `integer` Total number of submerchants that match the filter. **page** `integer` Current page. **per\_page** `integer` Number of submerchants per page. **total\_pages** `integer` Total number of pages. ```json 200 OK theme={null} { "data": [ { "id": 1234, "name": "Store X", "legal_name": "Store X LTDA", "document": "12345678000190", "has_markup": true, "payin": [ { "id": 55, "payment_method": "pix", "mode": "percent", "amount": "1.40", "min_charge_value": "1.00", "max_charge_value": "5.00" } ], "payout": [], "updated_at": "2026-09-28 10:49:13" }, { "id": 1235, "name": "Store Y", "legal_name": "Store Y LTDA", "document": "98765432000110", "has_markup": false, "payin": [], "payout": [], "updated_at": null } ], "total": 110, "page": 1, "per_page": 10, "total_pages": 11 } ``` ```json 422 Unprocessable Entity theme={null} { "message": "The given data was invalid.", "errors": { "per_page": [ "The per page field must not be greater than 500." ] } } ``` ```json 422 Unprocessable Entity - Unauthorized merchant theme={null} { "message": "The given data was invalid.", "errors": { "merchantId": [ "Unauthorized to perform this action." ] } } ``` ```json 500 Internal Server Error theme={null} { "error": "Failed to list subaccounts." } ``` ## Related Resources > [card] [Get Submerchant Markup](/api-reference/markup/submerchant/get-submerchant-markup) > > View the markup of a single submerchant > [card] [Configure Submerchant Markup](/api-reference/markup/submerchant/upsert-submerchant-markup) > > Set the markup of a submerchant > [card] [Batch Apply Submerchant Markup](/api-reference/markup/submerchant/batch-apply-submerchant-markup) > > Apply the same markup to many submerchants > [card] [About Markup](/markup/about-markup) > > Learn about markup types and configuration levels # Configure Submerchant Markup Source: https://docs.wepayout.co/api-reference/markup/submerchant/upsert-submerchant-markup PUT https://api.sandbox.wepayout.com.br/v2/account/{merchantId}/submerchants/{subMerchantId}/markups Create or replace the markup configuration of a submerchant. # Configure Submerchant Markup Use this endpoint to set a submerchant's own markup for each product and payment method. The submerchant's markup takes priority over the merchant's global markup, but not over an inline `markup` sent in the request. > [!WARNING] > > **This endpoint replaces the whole configuration.** Every call removes the submerchant's current markups and saves only the items in `markups`. Any product and payment method you leave out goes back to the global markup. ## Path Parameters **merchantId** `integer` *required* ID of the merchant (parent account). It must be one of the authenticated user's companies. **subMerchantId** `integer` *required* ID of the submerchant. It must be a submerchant of `merchantId`. ## Request Body **markups** `array[object]` *required* Markup configurations for the submerchant. Send between `1` and `8` items, and at most one item for each `product` and `payment_method` pair. **Markup Object** **product** `string` *required* Product where the markup will be applied. Allowed values: `payin`, `payout` **payment\_method** `string` *required* Payment method where the markup will be applied. Allowed values: * For `payin`: `pix`, `billet`, `credit_card` * For `payout`: `pix`, `ted` **mode** `string` *required* Type of markup to be applied. Allowed values: * `fixed`: fixed amount (BRL) per transaction * `percent`: percentage over the transaction amount **amount** `number` *required* Markup value. In BRL when `mode` is `fixed`, and a percentage when `mode` is `percent` (`1.5` means 1.5%). Must be greater than or equal to `0.01`. **min\_charge\_value** `number` Minimum markup amount (BRL) when `mode` is `percent`. Business rules: * **Required** when `mode` = `percent` * **Prohibited** when `mode` = `fixed` * Must be greater than or equal to `0.01` **max\_charge\_value** `number` Maximum markup amount (BRL) when `mode` is `percent`. Business rules: * **Required** when `mode` = `percent` * **Prohibited** when `mode` = `fixed` * Must be greater than or equal to `min_charge_value` > [!NOTE] > > Unlike the global markup, a submerchant markup with `mode` = `percent` requires **both** `min_charge_value` and `max_charge_value`. ## Request Examples ```json Payin and payout markup theme={null} { "markups": [ { "product": "payin", "payment_method": "pix", "mode": "percent", "amount": 1.4, "min_charge_value": 1.0, "max_charge_value": 5.0 }, { "product": "payin", "payment_method": "billet", "mode": "fixed", "amount": 2.0 }, { "product": "payout", "payment_method": "pix", "mode": "fixed", "amount": 0.8 } ] } ``` ```bash cURL theme={null} curl -X PUT "https://api.sandbox.wepayout.com.br/v2/account/123/submerchants/1234/markups" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "markups": [ { "product": "payin", "payment_method": "pix", "mode": "percent", "amount": 1.4, "min_charge_value": 1.0, "max_charge_value": 5.0 } ] }' ``` ## Response Returns the submerchant with its updated markup, with the same fields as [Get Submerchant Markup](/api-reference/markup/submerchant/get-submerchant-markup). ```json 200 OK theme={null} { "id": 1234, "name": "Store X", "legal_name": "Store X LTDA", "document": "12345678000190", "has_markup": true, "payin": [ { "id": 61, "payment_method": "pix", "mode": "percent", "amount": "1.40", "min_charge_value": "1.00", "max_charge_value": "5.00" } ], "payout": [], "updated_at": "2026-09-29 14:02:37" } ``` ```json 422 Unprocessable Entity theme={null} { "message": "The given data was invalid.", "errors": { "markups.0.payment_method": [ "The payment method ted is not allowed with product payin." ], "markups.1.min_charge_value": [ "Minimum and maximum values are required when the mode is percent." ], "markups.2.min_charge_value": [ "Minimum and maximum values do not apply to the fixed mode." ], "markups.3.max_charge_value": [ "The minimum value cannot be greater than the maximum value." ], "markups.4.payment_method": [ "There is more than one configuration for the same product and payment method." ] } } ``` ```json 422 Unprocessable Entity - Not a submerchant of this merchant theme={null} { "message": "The given data was invalid.", "errors": { "subMerchantId": [ "The subaccount 7777 does not belong to this account." ] } } ``` ```json 500 Internal Server Error theme={null} { "error": "Failed to create markup." } ``` ## Related Resources > [card] [Batch Apply Submerchant Markup](/api-reference/markup/submerchant/batch-apply-submerchant-markup) > > Apply the same markup to many submerchants > [card] [Remove Submerchant Markup](/api-reference/markup/submerchant/delete-submerchant-markup) > > Go back to the global markup > [card] [About Markup](/markup/about-markup) > > Learn about markup types and configuration levels > [card] [Create Merchant Markup](/api-reference/markup/account/create-merchant-markup) > > Configure the global markup # Authentication Source: https://docs.wepayout.co/authentication Learn how to authenticate with the WEpayments API The WEpayments API uses API keys to authenticate requests. Each API key is associated with a specific email address that has access to your WEpayments account. ## How to Create Your API Key To create and manage your API keys, follow the detailed instructions in our support center: > [card] [API Key Creation Guide](https://support.wepayments.com.br/support/legal/api-authentication) > > Learn how to create and manage your API keys in the WEpayments dashboard ## API Keys Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. **Important**: Each API key is linked to an email address with access to your WEpayments account. Make sure the email has the appropriate permissions for the operations you need to perform. ### Types of Keys * **Public Key**: Used for client-side operations * **Secret Key**: Used for server-side operations (keep this secure!) ## Making Authenticated Requests Authentication to the API is performed via HTTP Bearer Authentication. Provide your API key in the Authorization header: ```bash theme={null} Authorization: Bearer YOUR_API_KEY ``` ## Example Request ```bash cURL theme={null} curl https://api.wepayments.com/v1/transactions \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```javascript JavaScript theme={null} const response = await fetch('https://api.wepayments.com/v1/transactions', { headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); ``` ```python Python theme={null} import requests headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } response = requests.get('https://api.wepayments.com/v1/transactions', headers=headers) ``` ```php PHP theme={null} ``` ## Security Best Practices > [!WARNING] > > Never expose your secret API keys in client-side code, public repositories, or insecure locations. * Store API keys in environment variables * Use different keys for development and production * Rotate keys regularly * Implement proper access controls * Monitor API usage for suspicious activity ## Error Handling If authentication fails, you'll receive a `401 Unauthorized` response: ```json theme={null} { "error": { "code": "unauthorized", "message": "Invalid API key provided" } } ``` # Reference Source: https://docs.wepayout.co/banks/reference Understanding bank institutions in WEpayments # Banks Reference The Banks API provides access to the list of financial institutions available in Brazil for payment processing. ## Overview WEpayments supports a wide range of Brazilian banks and financial institutions. The Banks API allows you to retrieve the complete list of available institutions, which is essential for: * **Payment Processing**: Know which banks are supported for transactions * **User Interface**: Display bank options to your users * **Integration**: Validate bank codes before processing payments * **Compliance**: Ensure you're working with authorized institutions ## Available Institutions The API returns information about all banks registered with the Brazilian Central Bank (Banco Central do Brasil) that are supported by WEpayments. ### Institution Information Each institution in the list includes: | Field | Type | Description | | - | - | - | | `code` | string | ISPB code (unique identifier) | | `name` | string | Full institution name | | `short_name` | string | Abbreviated name | | `type` | string | Institution type (bank, payment institution, etc.) | ## Use Cases > [accordion] Bank Selection in UI > > Retrieve the list of institutions to populate a dropdown or selection menu in your application: > > ```javascript theme={null} > const banks = await fetchBanks(); > const bankOptions = banks.map(bank => ({ > value: bank.code, > label: bank.name > })); > ``` > [accordion] Bank Code Validation > > Validate bank codes before processing transactions: > > ```javascript theme={null} > function isValidBank(bankCode, bankList) { > return bankList.some(bank => bank.code === bankCode); > } > ``` > [accordion] Bank Name Display > > Convert bank codes to readable names for display: > > ```javascript theme={null} > function getBankName(bankCode, bankList) { > const bank = bankList.find(b => b.code === bankCode); > return bank ? bank.name : 'Unknown Bank'; > } > ``` > [accordion] Filtering by Type > > Filter institutions by type (e.g., only traditional banks): > > ```javascript theme={null} > const traditionalBanks = banks.filter(bank => bank.type === 'bank'); > ``` ## Common Banks in Brazil Some of the major banks you'll find in the list include: * **Banco do Brasil** - One of the largest banks in Brazil * **Caixa Econômica Federal** - Federal savings bank * **Itaú Unibanco** - Major private bank * **Bradesco** - One of the largest private banks * **Santander Brasil** - International bank with Brazilian operations * **Nubank** - Leading digital bank * **Inter** - Digital bank and payment institution * **PagSeguro** - Payment institution ## Best Practices > [!NOTE] > > **Cache the Bank List**: The list of institutions doesn't change frequently. Cache it in your application to reduce API calls and improve performance. > [!WARNING] > > **Keep Updated**: While the list is relatively stable, new institutions may be added. Refresh your cache periodically (e.g., weekly) to stay current. ### Caching Strategy ```javascript theme={null} // Example caching implementation const CACHE_DURATION = 7 * 24 * 60 * 60 * 1000; // 7 days async function getBanks() { const cached = localStorage.getItem('banks'); const cacheTime = localStorage.getItem('banks_timestamp'); if (cached && cacheTime) { const age = Date.now() - parseInt(cacheTime); if (age < CACHE_DURATION) { return JSON.parse(cached); } } // Fetch fresh data const banks = await fetchBanksFromAPI(); localStorage.setItem('banks', JSON.stringify(banks)); localStorage.setItem('banks_timestamp', Date.now().toString()); return banks; } ``` ## Next Steps > [card] [List Institutions](/api-reference/banks/list-institutions) > > View the API endpoint documentation > [card] [Payment Processing](/cash-out/about-payments) > > Learn how to process payments # About Charges Source: https://docs.wepayout.co/cash-in/about-charges Understanding the Payin solution and payment types We call the entire flow of issuing digital charges / payin as **Payin solutions**. Payin is the act of collecting funds from third parties and remitting them to the beneficiary. This dynamic happens, for example, whenever a purchase is made within Brazil and paid for in some e-commerce. WEpayment's role in this flow is to facilitate the processing and management of these charges and, through a single platform, enable the issuance of digital charges via **Boleto Bancário** and **Pix QR Code**. ## What You Can Do In general, with our Payin product you can: * Create a single payin via Pix QR Code * Create a single payin via Automatic Pix * Create a single payin via Boleto * Consult status of your payin's * Make withdrawals from your wallet * Check your wallet balance * Filter, sort and export lists of processed charges ## Payment Types > [card] [Pix QR Code](/cash-in/pix-qr-code) > > Instant payments available 24/7 > [card] [Automatic Pix](/cash-in/automatic-pix) > > Recurring payments with Pix > [card] [Boleto](/cash-in/boleto) > > Traditional payment method in Brazil ## Payment Flow Comparison > [card] Pix QR Code > > **Speed**: Instant (seconds) > > **Availability**: 24/7 > > **Payment Method**: QR Code or copy-paste > > **Confirmation**: Real-time > > **Best for**: Quick transactions, e-commerce > [card] Automatic Pix > > **Speed**: Instant (on due date) > > **Availability**: 24/7 > > **Payment Method**: Automatic debit > > **Confirmation**: Real-time > > **Best for**: Subscriptions, recurring bills > [card] Boleto > > **Speed**: Up to D+1 > > **Availability**: Business hours > > **Payment Method**: Bar code or boleto number > > **Confirmation**: Next business day > > **Best for**: Traditional customers, large amounts ## Use Cases > [accordion] E-commerce Checkout > > Integrate Pix and Boleto as payment options in your online store checkout. Customers can choose their preferred payment method based on urgency and convenience. > [accordion] Subscription Services > > Use **Automatic Pix** for seamless monthly collections with high retention. Boleto is a good alternative for B2B or older demographics. > [accordion] Marketplace Payments > > Enable sellers to receive payments via Pix for quick settlements or Boleto for traditional payment preferences. > [accordion] Bill Payments > > Allow customers to pay recurring bills effortlessly with **Automatic Pix**, or use Boleto for traditional scheduled payments. ## Getting Started **1. Create Your First Charge** Use the [Create Charge](/api-reference/cash-in/payin/create-charge) endpoint to generate a Pix QR Code, Automatic Pix or Boleto. **2. Monitor Payment Status** Use the [Get Unique Charge](/api-reference/cash-in/payin/get-unique-charge) endpoint to check payment status. **3. List All Charges** Use the [List Charge](/api-reference/cash-in/payin/list-charge) endpoint to view all your charges with filters. **4. Process Refunds** If needed, use the [Create Refund](/api-reference/cash-in/refund/create-refund) endpoint to refund Pix payments. ## Best Practices > [!NOTE] > > **Choose the Right Payment Method**: Offer both Pix and Boleto to cater to different customer preferences and use cases. > [!TIP] > > **Set Appropriate Expiration Dates**: > > * Pix: Typically 24-48 hours > * Boleto: Usually 3-7 days > [!WARNING] > > **Monitor Payment Status**: Always implement webhooks to receive real-time payment notifications instead of polling the API. ## Next Steps > [card] [Create Charge](/api-reference/cash-in/payin/create-charge) > > Learn how to create your first Pix or Boleto charge > [card] [Webhooks](/api-reference/account/webhook/webhook-setup) > > Set up webhooks to receive payment notifications > [card] [Refunds](/api-reference/cash-in/refund/create-refund) > > Understand how to process refunds for Pix payments > [card] [Account Balance](/api-reference/account/get-balance) > > Check your wallet balance and available funds # Automatic Pix Source: https://docs.wepayout.co/cash-in/automatic-pix Recurring payments with Pix Automatic Pix is a recurring payment solution built on the Pix infrastructure. It allows businesses to collect recurring payments automatically after a one-time authorization by the payer. Unlike traditional direct debit, which requires bilateral agreements between companies and each bank, Automatic Pix works across the entire Pix ecosystem, making it accessible to any user with a bank account. **Key Benefits:** > [card] For Your Business > > * **Reduced Delinquency**: Payments are collected automatically, mitigating forgetfulness. > * **Lower Costs**: Generally cheaper than credit card fees and boleto issuance. > * **Higher Conversion**: Accessible to customers who don't have credit cards. > * **Immediate Settlement**: Funds are available instantly, improving cash flow. > [card] For Your Customers > > * **Convenience**: "Set it and forget it" experience for recurring bills. > * **Control**: Easy management and cancellation via their banking app. > * **No Fees**: Typically free for individual payers (Pessoa Física). > * **Safety**: Built on the secure Pix infrastructure with established refund mechanisms. **Common Use Cases:** * **Utilities**: Water, electricity, gas, and internet bills. * **Subscriptions**: Streaming services, newspapers, and software (SaaS). * **Tuition**: Schools, universities, and specialized courses. * **Financial Services**: Insurance premiums, condos, and loan repayments. **How it works (Authorization Journeys):** The core of Automatic Pix is the **authorization**. The payer must grant permission for your business to debit their account periodically. We support the following journeys: > [accordion] Journey 2: QR Code Authorization > > The receiver sends a dedicated authorization QR Code, and the payer subscribes to the recurring payment by scanning it — no immediate charge is made. > > 1. **QR Code Generation**: The receiver generates and sends an Automatic Pix authorization QR Code to the payer. > 2. **Scan**: The payer scans the QR Code using their banking app. > 3. **Subscription**: The payer reviews the terms and confirms the recurring authorization via QR Code. > [accordion] Journey 3: QR Code Authorization + First Payment > > The receiver combines the first installment payment with the recurring authorization in a single QR Code, so the payer pays and subscribes in one step. > > 1. **QR Code Generation**: The receiver generates a QR Code that includes both the first installment payment and the Automatic Pix authorization. > 2. **Presentation**: The receiver presents the QR Code with the immediate payment and subscription bundled together. > 3. **Payment & Subscription**: The payer scans the QR Code, pays the first installment, and subscribes to the recurring payment in a single action. **Creating an Automatic Pix Charge:** Automatic Pix charges are created through the [Create Authorization](/api-reference/automatic-pix/authorizations/create) endpoint. To use Automatic Pix, include the `automatic_pix` object in the request body and set the `type` field according to the desired journey: | Value | Journey | Description | | - | - | - | | `optional` | Journey 2 | Authorization only — no immediate payment is charged. The payer subscribes to the recurring payment via QR Code. | | `immediate` | Journey 3 | First payment + authorization — the payer pays the first installment and subscribes to the recurring payment in a single step. | *** ## Amount Types When creating an authorization, you choose between two amount strategies by providing either `amount` or `minimum_authorization_amount` in the `automatic_pix` object. ### Fixed amount Provide `amount` to charge the same value every cycle. No PATCH is needed — the system automatically uses this value for every new schedule. ```json theme={null} "automatic_pix": { "amount": 5000, ... } ``` ### Variable amount Provide `minimum_authorization_amount` (and `authorization_amount` as the pre-authorized ceiling) to support cycles with different values. This is required if you plan to update the charge amount before each billing date. ```json theme={null} "automatic_pix": { "minimum_authorization_amount": 1000, "authorization_amount": 10000, ... } ``` **How each cycle's amount is resolved:** Each new schedule is created automatically using the authorization's `minimum_authorization_amount` as the default value. If you want to charge a different amount for a specific cycle, use the [Update Schedule](/api-reference/automatic-pix/schedules/update) endpoint to set a custom value **before the schedule moves beyond Pending status**. | Scenario | Amount charged | | - | - | | PATCH sent before the cycle's due date | Amount from the PATCH | | No PATCH sent | `minimum_authorization_amount` | > [!WARNING] > > The PATCH on a schedule only affects **that specific cycle**. Future cycles always revert to `minimum_authorization_amount` regardless of what was charged in the previous cycle. To permanently change the default amount for all future cycles, use the [Update Authorization](/api-reference/automatic-pix/authorizations/update) endpoint instead. # Automatic Pix Status Flow Source: https://docs.wepayout.co/cash-in/automatic-pix-status-flow Lifecycle of authorizations, schedules, and payments in Automatic Pix Automatic Pix has three interconnected lifecycles: the **authorization** (the payer's consent), the **schedule** (each individual billing cycle), and the **payin** (the actual money movement). Understanding how they relate is essential for a correct integration. *** ## Authorization Lifecycle The authorization represents the payer's ongoing consent to be debited. It is the parent of all schedules — every schedule belongs to one authorization. ```mermaid theme={null} graph TD A[Create Authorization] --> B[PENDING] B -->|Payer confirms via banking app| C[CONFIRMED] B -->|Payer declines or authorization expires| D[REJECTED] C -->|First schedule is automatically created| E[Schedule lifecycle begins] C -->|Merchant cancels via API| F[CANCELED] C -->|Payer cancels via their banking app| F F -->|All pending schedules are canceled in cascade| G[No more schedules] D -->|All pending schedules are canceled in cascade| G ``` > [!WARNING] > > Both **CANCELED** and **REJECTED** are terminal states. In both cases, all pending schedules linked to the authorization are automatically canceled and no new schedules will be created. ### Authorization Status Reference | ID | Status | Webhook | Description | | - | - | - | - | | 1 | Confirmed | ✅ Yes | Payer approved — first schedule is created automatically | | 2 | Pending | ✅ Yes | Authorization created, waiting for payer confirmation via QR Code | | 3 | Canceled | ✅ Yes | Canceled via merchant API or by the payer through their banking app | | 4 | Rejected | ✅ Yes | Payer declined during QR Code flow, or authorization expired | > [!NOTE] > > **Canceled vs Rejected**: CANCELED means an intentional termination — either by the merchant via API or by the payer revoking consent in their banking app after the authorization was already confirmed. REJECTED means the payer did not approve during the initial QR Code flow, or the authorization request expired. > > Both behave identically at the schedule level: all active schedules are canceled in cascade. > [accordion] 1 - Confirmed > > **Active status.** > > The payer scanned the QR Code and approved the recurring authorization via their banking app. The system automatically creates the first schedule using the `start_date` and `amount` configured in the authorization. > > **Next possible statuses**: Canceled > [accordion] 2 - Pending > > **Initial status.** > > The authorization was created and the QR Code is ready for the payer to scan. No charges occur while in this status. > > **Next possible statuses**: Confirmed, Rejected > [accordion] 3 - Canceled > > **Terminal status.** > > The authorization was canceled in one of two ways: > > * **Merchant via API**: Using the [Cancel Authorization](/api-reference/automatic-pix/authorizations/cancel) endpoint. > * **Payer via banking app**: The payer revoked the authorization directly in their bank's interface. > > In both cases, all pending schedules linked to this authorization are immediately canceled and no future schedules will be generated. > [accordion] 4 - Rejected > > **Terminal status.** > > The payer did not approve the authorization — either by explicitly declining the QR Code or by allowing it to expire without action. All pending schedules are canceled in cascade. *** ## Schedule Lifecycle Each schedule represents one billing cycle. Schedules are created **one at a time** — the next cycle is only generated after the current one reaches a definitive state. ```mermaid theme={null} graph TD A[Authorization CONFIRMED] --> B[PENDING] B -->|Dispatched to payment system| C[SENT] C -->|Payment system confirms| D[SCHEDULED] D -->|Next cycle schedule is created here| N[New PENDING schedule for next cycle] D -->|Debit executes on due date| E[PAID] D -->|Payment attempt fails| F[ON RETRY] D -->|Merchant cancels via API| G[CANCELED REQUESTED] F -->|Retry succeeds| E F -->|Retry exhausted| H[CANCELED] G -->|External system confirms| H H -->|Next cycle schedule is still created| N B -->|Merchant cancels via API| H ``` > [!WARNING] > > Canceling a **schedule** does not stop future billing. The system automatically creates the next cycle schedule whenever a schedule reaches SCHEDULED or CANCELED status — as long as the authorization is still active. To permanently stop all future charges, you must **cancel the authorization**. > [!NOTE] > > The schedule amount can only be updated when status is **PENDING**. Once the schedule moves beyond PENDING, only the authorization amount can be changed — and it will apply to the next cycle. See [Update Schedule](/api-reference/automatic-pix/schedules/update) for details. ### Schedule Status Reference | ID | Status | Webhook | Description | | - | - | - | - | | 1 | Pending | No | Created, waiting to be dispatched to the payment system | | 2 | Sent | No | Dispatched — cancellation is not possible at this point | | 3 | Scheduled | ✅ Yes | Confirmed by payment system — next cycle schedule is created | | 4 | On Retry | ✅ Yes | Attempt failed, system will retry automatically | | 5 | Canceled | ✅ Yes | Canceled — next cycle schedule is created if authorization is active | | 6 | Paid | ✅ Yes | Payment collected successfully | | 7 | Canceled Requested | No | Cancellation sent to external system, awaiting confirmation | > [accordion] 1 - Pending > > **Initial status.** > > The schedule was just created. The system dispatches pending attempts up to 3 days before the due date. The amount can still be updated via API at this stage (if the authorization is variable-amount type). > > **Can be canceled**: Yes — cancellation is immediate, no external call required. > > **Next possible statuses**: Sent, Canceled > [accordion] 2 - Sent > > **Intermediate status.** > > The schedule was dispatched to the external payment system. Cancellation via API is **not allowed** while in this status. > > **Next possible statuses**: Scheduled > [accordion] 3 - Scheduled > > **Active status.** > > The payment system confirmed the schedule for the due date. At this point, the system automatically creates the next billing cycle's schedule (as long as the authorization `end_date` has not been reached). > > **Can be canceled**: Yes — via API, which sends a cancellation request to the external system and transitions to Canceled Requested. > > **Next possible statuses**: Paid, On Retry, Canceled Requested > [accordion] 4 - On Retry > > **Intermediate status.** > > The payment attempt failed (e.g., insufficient funds) and the system is retrying automatically. > > **Next possible statuses**: Paid, Canceled > [accordion] 5 - Canceled > > **Terminal status.** > > The schedule was canceled. This can happen in three scenarios: > > * **Merchant cancels a PENDING schedule via API**: immediate cancellation, next cycle schedule is created. > * **External system returns CANCELLED or ERROR**: same behavior, next cycle schedule is created. > * **Authorization is canceled or rejected**: cascade cancellation — no next cycle schedule is created. > > **Next possible statuses**: none (terminal) > [accordion] 6 - Paid > > **Terminal status.** > > The payment was successfully collected by the payment system. The `metadata.amount` in the webhook reflects the exact charged amount. > > The next cycle schedule was already created when this schedule reached SCHEDULED status. > > **Next possible statuses**: none (terminal) > [accordion] 7 - Canceled Requested > > **Intermediate status.** > > The merchant requested cancellation via API for a schedule that was already SCHEDULED or ON RETRY. The cancellation request was sent to the external payment system and is awaiting confirmation. > > **Next possible statuses**: Canceled ### Schedule cancellation constraints Cancellation via API is blocked in the following conditions: * Schedule is in **Sent** status * Schedule is already in a final status (Paid or Canceled) * Current time is **22:00 or later** (Brazil timezone) * There is an **active payment attempt scheduled for today** *** ## Payin Lifecycle When a schedule is paid, the actual money movement is tracked as a payin. Intermediate statuses are not notified — your endpoint only receives a webhook on final events. ```mermaid theme={null} graph TD A[Schedule PAID] --> B[Payin created by payment system] B --> C[CREDITED] B --> D[CANCELED] B --> E[REJECTED] C -->|Webhook fired| F[Funds available] D -->|Webhook fired| G[No funds — payment returned] E -->|Webhook fired| H[No funds — rejected] ``` ### Payin Status Reference | Status | Webhook | Description | | - | - | - | | Credited | ✅ Yes | Payment received and funds are available | | Canceled | ✅ Yes | Payment was canceled — no funds transferred | | Rejected | ✅ Yes | Payment was rejected — no funds transferred | *** ## End-to-End Overview ```mermaid theme={null} graph TD A[Merchant creates authorization] --> B[PENDING] B -->|Payer confirms QR Code| C[CONFIRMED] B -->|Payer declines or expires| Z[REJECTED — billing stops] C --> D[Schedule: PENDING → SENT → SCHEDULED] D -->|Due date reached| E{Payment result} E -->|Success| F[Schedule: PAID] E -->|Failure| G[Schedule: ON RETRY → PAID or CANCELED] F --> H[Payin: CREDITED — webhook fired] D -->|Next cycle pre-created on SCHEDULED| I[New Schedule: PENDING] I --> D C -->|Merchant or payer cancels| Y[CANCELED — all schedules canceled, billing stops] ``` *** ## Webhook Summary | Event | Trigger | Webhook type | | - | - | - | | Any authorization status change | All statuses | Authorization webhook | | Schedule reaches Scheduled, On Retry, Canceled, or Paid | Status transition | Schedule webhook | | Payin credited, canceled, or rejected | Final payin status | Payin webhook | See [Webhooks](/cash-in/automatic-pix-webhooks) for full payload details and signature verification. # Webhooks Source: https://docs.wepayout.co/cash-in/automatic-pix-webhooks Real-time notifications for Automatic Pix events Automatic Pix sends webhook notifications to your configured endpoint whenever a relevant status change occurs. There are three distinct webhook types: **authorization** updates, **schedule** updates, and **payin** (transaction) updates. *** ## Authorization Webhook Sent whenever an authorization transitions to a new status. Your endpoint receives a `POST` request with the following payload. **Trigger statuses:** | Status ID | Status Name | Description | | - | - | - | | 1 | Confirmed | Authorization approved by the payer | | 2 | Pending | Authorization created and awaiting payer confirmation | | 3 | Canceled | Authorization was canceled | | 4 | Rejected | Authorization was rejected | > [!NOTE] > > All authorization status changes trigger a webhook — there are no silenced intermediate statuses. **Payload:** ```json theme={null} { "entity": "authorization", "id": 3081, "contract_id": "10000:1234:2:aabbccdd112233aabbccdd112233aabb", "status": { "id": 1, "name": "Confirmed" }, "updated_at": "2026-01-15T10:00:00.000-03:00" } ``` **Field reference:** | Field | Type | Description | | - | - | - | | `entity` | string | Always `"authorization"` | | `id` | integer | Internal authorization ID | | `contract_id` | string | Authorization contract identifier | | `status.id` | integer | Numeric status code | | `status.name` | string | Human-readable status name | | `updated_at` | string | ISO 8601 timestamp of the status change | *** ## Schedule Webhook Sent whenever a schedule transitions to a notifiable status. Your endpoint receives a `POST` request with the following payload. **Trigger statuses:** | Status ID | Status Name | Description | | - | - | - | | 3 | Scheduled | Payment successfully scheduled | | 4 | On Retry | Payment failed and is being retried | | 5 | Canceled | Payment was canceled | | 6 | Paid | Payment completed successfully | > [!NOTE] > > Statuses `Pending` (1), `Sent` (2), and `Canceled Requested` (7) do **not** trigger a webhook. **Payload:** ```json theme={null} { "entity": "schedule", "id": 1042, "contract_id": "10000:1234:2:aabbccdd112233aabbccdd112233aabb", "status": { "id": 6, "name": "Paid" }, "metadata": { "amount": 150.00, "tx_id": "WP01AABBCC112233DDEEFF4455667788" }, "updated_at": "2026-01-15T10:30:00.000-03:00" } ``` **Field reference:** | Field | Type | Description | | - | - | - | | `entity` | string | Always `"schedule"` | | `id` | integer | Internal schedule ID | | `contract_id` | string | Authorization contract identifier | | `status.id` | integer | Numeric status code | | `status.name` | string | Human-readable status name | | `metadata.tx_id` | string | Internal transaction identifier generated by WEpayments | | `metadata.amount` | float | Amount charged — only present when `status.id` is `6` (Paid) | | `sub_status` | object | Optional. Additional context for the transition (e.g., cancellation reason) | | `updated_at` | string | ISO 8601 timestamp of the status change | *** ## Payin Webhook Sent when an Automatic Pix payin reaches a final or relevant status. All intermediate statuses are silenced — the webhook fires only on the events below. **Trigger statuses:** **4 — Credited** → Payment successfully received **Canceled** → Payment was canceled **Rejected** → Payment was rejected **Payload:** ```json theme={null} { "id": 200001, "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "invoice": "10000:1234:2:aabbccdd112233aabbccdd112233aabb-20260115", "end_to_end": "E99999999202601151330xXxXxXxXxXx", "status": { "id": 4, "name": "Credited" }, "metadata": { "paid_amount": 150.00, "payer": { "document": "12345678900" }, "contract_id": "10000:1234:2:aabbccdd112233aabbccdd112233aabb", "bank_payer": { "name": "341 - ITAÚ UNIBANCO S.A.", "bank_ispb": "60701190", "bank_account": null, "bank_branch": null, "bank_account_type": null } }, "updated_at": "2026-01-15T13:30:00.000000Z" } ``` **Field reference:** | Field | Type | Description | | - | - | - | | `id` | integer | Internal payin ID | | `hash` | string | SHA-256 fingerprint of this payin, used for signature verification | | `invoice` | string | Composed of the `contract_id` and the payment date (`contract_id-YYYYMMDD`) | | `end_to_end` | string | PIX end-to-end identifier assigned by the Brazilian payment system (SPI) — can be used for reconciliation and dispute resolution | | `status.id` | integer | Numeric status code | | `status.name` | string | Human-readable status name | | `metadata.paid_amount` | float | Amount actually received | | `metadata.payer.document` | string | Payer's CPF/CNPJ | | `metadata.contract_id` | string | Authorization contract identifier | | `metadata.bank_payer` | object | Payer's bank details — only present when your contract has `send_bank_payer_into_webhook` enabled | | `updated_at` | string | ISO 8601 timestamp of when the status was recorded | *** ## Signature Verification **Payin webhooks** support the recommended [HMAC-SHA256 signature](/concepts/webhooks#hmac-sha256-signature). When your account has a webhook registered for the `payin` event with a `secret`, the request includes the `x-webhook-wp-type` (`payin-pix`), `x-webhook-wp-timestamp` and `x-webhook-wp-signature` headers, where: ``` x-webhook-wp-signature = hex( HMAC_SHA256( secret, raw_body + x-webhook-wp-timestamp ) ) ``` See [Webhook Signature](/concepts/webhooks) for all headers and verification examples. > [!WARNING] > > **Deprecated:** Authorization and Schedule webhooks, and Payin webhooks without a registered webhook, are still signed with the deprecated API key signature. See [Webhook Signature](/concepts/webhooks). > [!WARNING] > > Always validate the signature before processing any webhook payload to ensure the request originates from WEpayments. # Boleto Source: https://docs.wepayout.co/cash-in/boleto Traditional payment method in Brazil This payment method also brings a bar code number, that enables the customer to pay either scanning the Bar code number, or with the boleto number the client will pay in the internet banking app, lottery or payments app. > [!WARNING] > > **Payment confirmation up to D+1.** **Key Features:** * Traditional payment method in Brazil * Bar code scanning * Boleto number for manual payment * Payment at banks, lotteries, or apps * Confirmation within 1 business day **How it works:** 1. Generate a Boleto charge 2. Customer receives the boleto with bar code 3. Customer pays at bank, lottery, or app 4. Payment is processed by the banking system 5. Confirmation received within D+1 6. Funds are credited to your wallet # Payin Webhook Source: https://docs.wepayout.co/cash-in/payin-webhook Receive real-time notifications about payin status changes Webhooks allow you to receive automatic notifications about payin events in real-time. When a payin status changes, WEpayments will send a POST request to your registered webhook URL with the updated transaction data. ## How It Works 1. **Configure your notification URL** when creating the payin charge using the `notification_url` parameter 2. **Receive notifications** automatically when payin status changes 3. **Process the payload** containing the complete payin details 4. **Return a 200 OK** response to acknowledge receipt > [!NOTE] > > Webhooks are sent only for **final statuses**: Credited, Canceled, Rejected ## Setting Up Webhooks To receive webhook notifications for payin transactions, include the `notification_url` parameter when [creating a charge](/api-reference/cash-in/payin/create-charge): ```json theme={null} { "invoice": "ORDER-12345", "notification_url": "https://your-domain.com/webhooks/payin", "payment_method": "pix", "amount": 10000, "currency": "BRL", "country": "BR", "buyer": { ... } } ``` The notification URL is defined in the `notification_url` field in the request body when creating a charge. Each charge can have its own notification URL, allowing you to route notifications to different endpoints based on your needs. ## Webhook Payload When a payin status changes, you'll receive a POST request with the following data: ### Response Fields **id** `integer` Payin ID Example: `113589233` **hash** `string` Unique hash identifier for the payin transaction Example: `54a3cbc66f4ec54a10826edc62ff3f8f8f706c5c54a9db22e1f57fcfff4516d8` **invoice** `string` Payin invoice Example: `eb21ce52-2897-475b-85af-a5201f4035bf` **end\_to\_end** `string` Payin end-to-end identifier Example: `E12345678202603191234567890AB1` **status** `object` Object that contains the current status of your payin. **Status Object** **id** `integer` Current status ID of your payin Example: `4` **name** `string` Name of the current status of your payin Example: `Credited` **status\_detail** `object` This object will only be returned if the payin is rejected and the merchant is using the "Account Mismatch" functionality. It provides more details on the reason for the rejection. **Status Detail Object** **code** `string` Code that represents the reason for the rejection Example: `WE0001` See [Status Detail Codes](#status-detail-codes) table below for all possible values. **detail** `string` Explanation of the reason for the rejection Example: `The payment was made from an unregistered account.` **updated\_at** `string` Last update of your payin. Format: `` Example: `2024-09-09T20:55:56.000000Z` **metadata** `object` Additional metadata about the payment. **Metadata Object** **paid\_amount** `number` Amount paid by the end user. > [!WARNING] > > Since the `paid_amount` parameter contains sensitive financial information, we recommend considering this data only if you are verifying the webhook signature. Example: `97` **payer** `object` Information about the payer of the payin. **Payer Object** **document** `string` Payer's document (CPF/CNPJ) **bank\_payer** `object` Information about the end user's bank account used to pay the QR Code. **Bank Payer Object** **name** `string` Bank name Example: `033 - BCO SANTANDER (BRASIL) S.A.` **bank\_ispb** `string` Bank ISPB code **bank\_account** `string` Bank account number **bank\_branch** `string` Bank branch (agência) **bank\_account\_type** `string` Account type (e.g. `CACC` for checking account) ## Example Payload ```json theme={null} { "id": 123456789, "hash": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456", "invoice": "ORDER-12345", "end_to_end": "E12345678202603191234567890AB1", "status": { "id": 4, "name": "Credited" }, "metadata": { "paid_amount": 97, "payer": { "document": "12345678900" }, "bank_payer": { "name": "033 - BCO SANTANDER (BRASIL) S.A.", "bank_ispb": "60746948", "bank_account": "12345678", "bank_branch": "1234", "bank_account_type": "CACC" } }, "updated_at": "2026-03-19T15:13:18.000000Z" } ``` ## Status Codes Common payin status codes: | Status ID | Status Name | Description | | - | - | - | | 1 | Created | Charge has been created | | 2 | Canceled | Charge canceled due to expiration | | 3 | Paid | Charge successfully paid | | 4 | Credited | Amount is paid and available for withdrawal | | 5 | Drop\_requested | Cancellation requested | | 7 | Rejected | Charge rejected due to compliance | See [Payin Status Flow](/cash-in/status-flow) for detailed status information. ## Status Detail Codes When a PIX transaction is rejected, the `status_detail.code` field provides specific information about the rejection reason: | Code | Description | | - | - | | `reason_payer_divergence` | CPF mismatch | | `reason_payer_restriction_deceased_holder` | CPF restriction: deceased holder | | `reason_payer_restriction_canceled` | CPF restriction: canceled document | | `reason_payer_restriction_suspended` | CPF restriction: suspended document | | `reason_payer_pending_regularization` | CPF restriction: pending regularization | | `reason_payer_restriction_unknown` | CPF restriction: unknown document | | `gl_cpf_payer_restriction_underage` | CPF restriction: underage (Brazilian law) | | `reason_payer_restriction_age_above_limit` | Restriction: age above limit (> 80 years) | | `pending_challenge` | Pending challenge | | `reason_payer_restriction_receita` | CPF restriction (Tax Authority) | | `payer_restriction_high_risk` | CPF high risk | | `pending_review_manual` | Payment created; awaiting manual review | | `payer_restriction` | Rejected per compliance policy | | `reason_payer_restriction_pep` | PEP (Politically Exposed Person) | | `reason_payer_restriction_list_restrict` | CPF on restriction list | | `reason_payer_restriction_cpf_irregular` | Irregular CPF | | `reason_payer_restriction_judicial_block` | Judicial block | | `reason_payer_restriction_partners_and_ownership` | Certified restriction (partners/ownership) | | `reason_payer_restriction_ofac` | CPF on OFAC list | | `reason_payer_restriction_interpol` | CPF on INTERPOL list | | `reason_payer_restriction_onu` | CPF on UN list | | `reason_payer_restriction_euro` | CPF on European restriction list | | `WE0001` | The payment was made from an unregistered account | | `WE0002` | The payment was made from an unauthorized institution | | `reason_payer_restriction_pld` | KYC restriction | > [!NOTE] > > These codes are only returned when the payin status is **Rejected** and the merchant has the "Account Mismatch" functionality enabled. ## Webhook Endpoint Requirements Your webhook endpoint must: * **Accept POST requests** - All webhook notifications are sent via POST * **Use HTTPS** - Only secure HTTPS URLs are accepted * **Return 200 OK** - Respond with a 200 status code within 5 seconds * **Be publicly accessible** - The endpoint must be reachable from the internet ## Retry Policy > [!NOTE] > > If your endpoint responds with a failure (status code different from 200), **15 retry attempts** will be made to deliver the webhook notification. ## Best Practices > [!NOTE] > > **Always Respond 200 OK**: Your endpoint must respond with HTTP 200 to acknowledge receipt. > [!WARNING] > > **Validate Webhook Signature**: Always validate the webhook signature to ensure it's from WEpayments. Register a webhook `secret` to receive the recommended HMAC-SHA256 signature in the `x-webhook-wp-signature` header — the API key based signature is deprecated. See [Webhook Signature Documentation](/concepts/webhooks) for details. > [!WARNING] > > **Verify paid\_amount**: The `paid_amount` field represents the actual amount paid by the customer and is important to consider for reconciliation. ## Related Resources > [card] [Status Flow](/cash-in/status-flow) > > Understand payin status lifecycle # Pix QR Code Source: https://docs.wepayout.co/cash-in/pix-qr-code Instant payments available 24/7 This payment method also brings a copy-and-paste code, that enables the customer to pay either scanning the QR Code, or with the copy-and-paste code the client will pay in the internet banking app. > [!NOTE] > > **Payment confirmation in a few seconds.** **Key Features:** * Instant payment confirmation * QR Code scanning * Copy-and-paste code option * Available 24/7 * No intermediaries **How it works:** 1. Generate a Pix QR Code charge 2. Customer scans the QR Code or copies the code 3. Customer confirms payment in their banking app 4. Payment is confirmed in seconds 5. Funds are credited to your wallet # Rejection Reasons Source: https://docs.wepayout.co/cash-in/rejection-reasons Understanding payin rejection codes and error messages # Rejection reasons payin One of the most likely reasons for receiving a status code 400 in response to a request is compliance validation. In this scenario, the status will be set to false, indicating that the request was not fulfilled. Additionally, additional details will be provided to facilitate understanding of the error. > [!WARNING] > > **Message Field**: "Compliance validation error" > > **HTTP code**: 400 ## Data Object Upon receiving this error code, review the details provided in the Data object to understand the nature of the restriction and take appropriate action to correct the request: * **Code**: Indicates the specific type of restriction that caused the error * **Description**: Provides a brief description of the reason for the error ## Rejection Codes > [accordion] restriction\_overdue > > **Code**: `restriction_overdue` > > **Description EN**: Rejected due to document restriction > > **Description PT-BR**: Rejeição devido a restrição de documento > [accordion] restriction\_underage > > **Code**: `restriction_underage` > > **Description EN**: Rejected due to document restriction underage Brazilian law > > **Description PT-BR**: Rejeição devido a restrição de documento menor de idade pela lei brasileira > [accordion] restriction\_deceased\_holder > > **Code**: `restriction_deceased_holder` > > **Description EN**: Rejected due to document restriction deceased holder > > **Description PT-BR**: Rejeição devido a restrição de documento de falecido > [accordion] restriction\_canceled > > **Code**: `restriction_canceled` > > **Description EN**: Rejected due to document restriction canceled document > > **Description PT-BR**: Rejeição devido a restrição de documento cancelado > [accordion] restriction\_unknown > > **Code**: `restriction_unknown` > > **Description EN**: Rejected due to document restriction unknown document > > **Description PT-BR**: Rejeição devido a restrição de documento não encontrado na Receita Federal > [accordion] restriction\_pending\_regularization > > **Code**: `restriction_pending_regularization` > > **Description EN**: Rejected due to document restriction pending of regularization > > **Description PT-BR**: Rejeição devido a restrição de documento pendente de atualização > [accordion] restriction\_suspended > > **Code**: `restriction_suspended` > > **Description EN**: Rejected due to document restriction suspended > > **Description PT-BR**: Rejeição devido a restrição de documento suspenso > [accordion] restriction\_partners\_and\_ownership > > **Code**: `restriction_partners_and_ownership` > > **Description EN**: Rejected due to document restriction partners and ownership > > **Description PT-BR**: Rejeição devido a restrição de documento de sócios e titularidades > [accordion] restriction\_judicial\_block > > **Code**: `restriction_judicial_block` > > **Description EN**: Rejected due to document restriction judicial block > > **Description PT-BR**: Rejeição devido a restrição de documento bloqueio judicial > [accordion] restriction\_cpf\_irregular > > **Code**: `restriction_cpf_irregular` > > **Description EN**: Rejected due to document restriction > > **Description PT-BR**: Rejeição devido a restrição de documento > [accordion] restriction\_list\_restrict > > **Code**: `restriction_list_restrict` > > **Description EN**: Rejected due to document restriction > > **Description PT-BR**: Rejeição devido a restrição de documento > [accordion] restriction\_pep > > **Code**: `restriction_pep` > > **Description EN**: Rejected due to document restriction PEP (Politically Exposed Person) > > **Description PT-BR**: Rejeição devido a restrição de documento PEP (Pessoa Politicamente Exposta) > [accordion] restriction\_age\_above\_limit > > **Code**: `restriction_age_above_limit` > > **Description EN**: Rejected due to restriction age as per compliance policy > > **Description PT-BR**: Rejeição devido a restrição de idade conforme política de conformidade > [accordion] restriction\_ofac > > **Code**: `restriction_ofac` > > **Description EN**: Rejected due to document restriction on OFAC list > > **Description PT-BR**: Rejeição devido a restrição de documento na lista do OFAC > [accordion] restriction\_interpol > > **Code**: `restriction_interpol` > > **Description EN**: Rejected due to document restriction on INTERPOL list > > **Description PT-BR**: Rejeição devido a restrição de documento na lista da INTERPOL > [accordion] restriction\_onu > > **Code**: `restriction_onu` > > **Description EN**: Rejected due to document restriction on ONU list > > **Description PT-BR**: Rejeição devido a restrição de documento na lista da ONU > [accordion] restriction\_euro > > **Code**: `restriction_euro` > > **Description EN**: Rejected due to document restriction on EURO list > > **Description PT-BR**: Rejeição devido a restrição de documento na lista da EURO ## Error Response Example ```json theme={null} { "status": false, "message": "Compliance validation error", "data": { "code": "restriction_underage", "description": "Rejected due to document restriction underage Brazilian law" } } ``` ## Handling Rejection Errors **1. Identify the Error Code** Check the `code` field in the response to identify the specific restriction type. **2. Review the Description** Read the `description` field to understand the reason for rejection. **3. Take Corrective Action** Based on the error code, take appropriate action: * Update document information * Verify customer age and eligibility * Check compliance requirements * Contact support if needed **4. Retry the Request** After correcting the issue, retry the payin creation request. ## Common Scenarios > [card] Underage Customer > > **Code**: `restriction_underage` > > **Solution**: Verify customer age. Brazilian law requires customers to be 18+ for financial transactions. > [card] Invalid Document > > **Code**: `restriction_canceled` or `restriction_unknown` > > **Solution**: Verify document number is correct and valid with Brazilian Federal Revenue. > [card] PEP Restriction > > **Code**: `restriction_pep` > > **Solution**: Additional compliance checks required for Politically Exposed Persons. > [card] Judicial Block > > **Code**: `restriction_judicial_block` > > **Solution**: Document has judicial restrictions. Customer must resolve legal issues. ## Best Practices > [!NOTE] > > **Validate Documents Early**: Implement document validation before attempting to create a payin to provide better user experience. > [!WARNING] > > **Compliance Requirements**: Always ensure customer documents are valid and comply with Brazilian regulations before processing transactions. > [!TIP] > > **Error Handling**: Implement proper error handling to gracefully inform customers about rejection reasons and guide them on next steps. ## Related Resources > [card] [Create Charge](/api-reference/cash-in/payin/create-charge) > > Learn how to create charges with proper validation > [card] [About Charges](/cash-in/about-charges) > > Understand the Payin solution and payment types # Payin Status Flow Source: https://docs.wepayout.co/cash-in/status-flow Understanding the lifecycle of PIX and Boleto payin transactions We will show the life cycle for PIX payins, regarding the status. The notification sent to the payin will be based on the **final status**. The final status represents when the payment is completed, approved by compliance, and with the value available for withdrawal. > [!WARNING] > > Charges (payin) in final statuses (`CREDITED`, `CANCELED`, `REJECTED`) can no longer be updated. The status will follow the cycle below: ## Payin pix ```mermaid theme={null} graph TD A[CREATED] --> B[Payment done by customer] A --> C[CANCELED] B --> D[CREDITED] B --> E[REJECTED] C --> F[Canceled by operator/Expired] D --> G[Payment approved] E --> H[Blocked by compliance review] G --> I[SEND WEBHOOK] H --> J[SEND WEBHOOK] I --> K[Webhook sent] J --> L[Webhook sent] ``` > [!NOTE] > > PIX notifications will be completed shortly after the payment is done. ### PIX Status Flow Explanation * **CREATED (1)**: Initial status when the payin is created * **CANCELED (2)**: Canceled by operator or expired * **PAID (3)**: Payment paid * **CREDITED (4)**: Payment credited, final status * **REJECTED (7)**: Blocked by compliance review ## Payin boleto ```mermaid theme={null} graph TD A[CREATED] --> B[Payment done by customer] A --> C[DROP_REQUESTED] B --> D[CREDITED] C --> E[CANCELED] C --> F[When the boleto has expired and it goes into the cancellation queue] D --> G[Payment approved] E --> H[Canceled by operator/Expired] G --> I[SEND WEBHOOK] H --> J[SEND WEBHOOK] I --> K[Webhook sent] J --> L[Webhook sent] ``` > [!WARNING] > > Payments made by boleto do not undergo compliance validation after payment, as it is not possible to automatically refund this form of payment. > > Boleto notifications will be cleared after 1 working days. > [!NOTE] > > **Note**: refunds done to customers must be done apart the api ### Boleto Status Flow Explanation * **CREATED (1)**: Initial status when the payin is created * **CANCELED (2)**: Canceled by operator or expired * **PAID (3)**: Payment paid * **CREDITED (4)**: Payment credited, final status * **DROP\_REQUESTED (5)**: Cancellation requested (when boleto expires) ## Possible charge (payin) status | ENUM\_CODE | STATUS | EXPLANATION | | | - | - | - | - | | 1 | Created | The first status when the payin is created | | | 2 | Canceled | Payin canceled due to expiration | | | 3 | Paid | Payin successfully paid | | | 4 | Credited | The amount is paid and available for withdrawal / settlement | | | 5 | Drop\_requested | Payin transaction canceled at the user's request | | | 7 | Rejected | Payin rejected due to compliance reason | | ## Status Details > [accordion] 1 - Created > > **Initial Status** > > This is the first status when a payin is created. The charge is active and waiting for payment. > > * **PIX**: QR Code is generated and ready to be scanned > * **Boleto**: Boleto is generated and ready to be paid > > **Next possible statuses**: Paid, Canceled, Drop\_requested > [accordion] 2 - Canceled > > **Final Status** > > Payin was canceled due to expiration or operator action. > > **Reasons**: > > * Expiration date reached without payment > * Manual cancellation by operator > * Automatic cancellation after drop\_requested > > **Action**: No further action possible. Create a new charge if needed. > [accordion] 3 - Paid > > **Intermediate Status** > > Payment was successfully received but is under compliance review. > > * **PIX**: Payment confirmed in seconds > * **Boleto**: Payment confirmed after bank processing (D+1) > > **Next possible statuses**: Credited, Rejected > [accordion] 4 - Credited > > **Final Status** > > The amount is paid, approved by compliance, and available for withdrawal/settlement. > > **This is the final success status**: > > * Funds are available in your wallet > * Webhook notification is sent > * Ready for withdrawal or settlement > > **Action**: Funds can now be withdrawn or used for payouts. > [accordion] 5 - Drop\_requested > > **Intermediate Status** > > Payin transaction cancellation was requested. > > * **PIX**: Canceled immediately > * **Boleto**: Enters cancellation queue, takes 1 working day > > **Next status**: Canceled > [accordion] 7 - Rejected > > **Final Status** > > Payin was rejected due to compliance validation. > > **Reasons**: > > * Failed compliance checks > * Document restrictions > * Blocked by fraud prevention > > **Action**: Review rejection reason and create new charge with corrected information. > > See [Rejection Reasons](/cash-in/rejection-reasons) for more details. ## Webhook Notifications > [!NOTE] > > Webhooks are sent only for **final statuses**: Credited, Canceled, Rejected ### When to Expect Webhooks > [tab] PIX > > **Fast Notifications** > > PIX webhooks are sent shortly after payment completion: > > * **Credited**: Within seconds after payment approval > * **Rejected**: Within seconds if compliance fails > * **Canceled**: Immediately after cancellation > > ```json theme={null} > { > "id": 32457, > "invoice": "YOUR-CODE1234", > "end_to_end": "END-TO-END-ID", > "status": { > "id": 4, > "name": "Credited" > }, > "updated_at": "2024-06-12T23:04:27.000000Z" > } > ``` > [tab] Boleto > > **Delayed Notifications** > > Boleto webhooks are sent after bank processing: > > * **Credited**: After 1 working day > * **Canceled**: After 1 working day (if drop\_requested) > > ```json theme={null} > { > "id": 32462, > "invoice": "YOUR-CODE1234", > "end_to_end": "END-TO-END-ID", > "status": { > "id": 4, > "name": "Credited" > }, > "updated_at": "2024-06-13T10:30:00.000000Z" > } > ``` ## Status Monitoring **1. Create Charge** Use [Create Charge](/api-reference/cash-in/payin/create-charge) to generate a PIX or Boleto. Initial status: **Created (1)** **2. Customer Pays** Customer completes payment using PIX QR Code or Boleto. Status changes to: **Paid (3)** **3. Compliance Check** System performs compliance validation (PIX only). * If approved: **Credited (4)** * If rejected: **Rejected (7)** **4. Receive Webhook** Webhook notification is sent with final status. Your system receives the notification and processes accordingly. ## Best Practices > [card] Implement Webhooks > > Always use webhooks instead of polling to receive status updates efficiently. > [card] Handle All Statuses > > Implement logic to handle all possible statuses in your application. > [card] Check Final Status > > Only consider Credited (4) as successful payment. Paid (3) is still under review. > [card] Monitor Expiration > > Set appropriate expiration dates and handle Canceled status gracefully. ## Related Resources > [card] [Create Charge](/api-reference/cash-in/payin/create-charge) > > Create PIX or Boleto charges > [card] [Get Charge](/api-reference/cash-in/payin/get-unique-charge) > > Check charge status > [card] [Payin Webhook](/cash-in/payin-webhook) > > Configure webhook notifications > [card] [Rejection Reasons](/cash-in/rejection-reasons) > > Understand rejection codes > [card] [About Charges](/cash-in/about-charges) > > Learn about Payin solutions > [card] [Refunds](/api-reference/cash-in/refund/create-refund) > > Process PIX refunds ## Additional Notes > [!NOTE] > > You can check the reasons why our compliance team will reject a payment in our article [Rejection reasons payin](/cash-in/rejection-reasons). > [!NOTE] > > For more information about webhook, check our article [Webhook Signature Documentation](/concepts/webhooks). # Test Documents Source: https://docs.wepayout.co/cash-in/test-documents Use these test documents to simulate different payin scenarios in the sandbox environment. Each document triggers specific charge outcomes for testing your integration. ## Successful Charges For charges that should be **approved and credited**, use one of the following documents: | Document | Type | Final Status | Flow | Description | | - | - | - | - | - | | **58713371126** | CPF | Credited | Created → Paid → Credited | Charge approved and credited successfully | | **59730932395** | CPF | Credited | Created → Paid → Credited | Charge approved and credited successfully | | **00000000E08G12** | CNPJ | Credited | Created → Paid → Credited | Alphanumeric CNPJ, approved and credited successfully | > [!NOTE] > > **Alphanumeric CNPJ.** A CNPJ has 14 characters: the first 12 may be digits > (`0-9`) or uppercase letters (`A-Z`), and the last 2 are always numeric check > digits. Send it without separators, in uppercase — `00000000E08G12`, not > `00.000.000/E08G-12`. Numeric CNPJs keep working exactly as before. ### Example - Successful Charge ```json theme={null} { "pix": { "expire_date": "2025-12-31T23:59:59" }, "buyer": { "name": "João Silva", "document": { "type": "CPF", "number": "58713371126" }, "email": "joao.silva@example.com" }, "amount": 10000, "invoice": "unique-invoice-id", "country": "BR", "currency": "BRL", "payment_method": "pix" } ``` ### Example - Successful Charge with an Alphanumeric CNPJ ```json theme={null} { "pix": { "expire_date": "2025-12-31T23:59:59" }, "buyer": { "name": "Empresa Exemplo LTDA", "document": { "type": "CNPJ", "number": "00000000E08G12" }, "email": "financeiro@example.com" }, "amount": 10000, "invoice": "unique-invoice-id", "country": "BR", "currency": "BRL", "payment_method": "pix" } ``` ## Rejected Charges To test a **rejected charge**, use the following CPF document: | Document (CPF) | Final Status | Flow | Rejection Reason | | - | - | - | - | | **90836247060** | Rejected | Created → Rejected | The payment was made from an unauthorized institution. | ### Example - Rejected Charge ```json theme={null} { "pix": { "expire_date": "2025-12-31T23:59:59" }, "buyer": { "name": "Maria Santos", "document": { "type": "CPF", "number": "90836247060" }, "email": "maria.santos@example.com" }, "amount": 5000, "invoice": "unique-invoice-id", "country": "BR", "currency": "BRL", "payment_method": "pix" } ``` ## Error Simulation To simulate a **400 error response**, use the following CPF document: | Document (CPF) | Response | Error Message | | - | - | - | | **76145193026** | 400 Bad Request | Failed to send payin to processor | ### Example - Error Response ```json Request theme={null} { "pix": { "expire_date": "2025-12-31T23:59:59" }, "buyer": { "name": "Carlos Oliveira", "document": { "type": "CPF", "number": "76145193026" }, "email": "carlos.oliveira@example.com" }, "amount": 7500, "invoice": "unique-invoice-id", "country": "BR", "currency": "BRL", "payment_method": "pix" } ``` ```json Response (400) theme={null} { "message": "Failed to send payin to processor" } ``` ## Testing Flow **1. Choose test scenario** Decide whether to test a successful charge, rejection, or error response **2. Select test document** Choose the appropriate CPF document from the tables above **3. Create charge** Use the [Create Charge](/api-reference/cash-in/payin/create-charge) endpoint with the test document **4. Monitor status** Check the charge status using webhooks or the [Get Unique Charge](/api-reference/cash-in/payin/get-unique-charge) endpoint **5. Verify completion** Confirm the charge reaches the expected final status ## Best Practices > [!NOTE] > > **Sandbox Environment**: Always use test documents in the sandbox environment. These documents are specifically configured for testing purposes. > [!TIP] > > **Unique Invoice**: Always use a unique invoice ID for each charge to avoid duplicates and ensure proper tracking. ## Common Test Scenarios > [accordion] Successful Charge - Credited > > **Document**: 58713371126 > > **Expected Flow**: Created → Paid → Credited > > **Expected Result**: Charge approved and credited successfully > > ```json theme={null} > { > "pix": { > "expire_date": "2025-12-31T23:59:59" > }, > "buyer": { > "name": "João Silva", > "document": { > "type": "CPF", > "number": "58713371126" > }, > "email": "joao.silva@example.com" > }, > "amount": 15000, > "invoice": "test-charge-success-001", > "country": "BR", > "currency": "BRL", > "payment_method": "pix" > } > ``` > [accordion] Rejected Charge - Unauthorized Institution > > **Document**: 90836247060 > > **Expected Flow**: Created → Rejected > > **Expected Result**: Charge rejected with reason "The payment was made from an unauthorized institution." > > ```json theme={null} > { > "pix": { > "expire_date": "2025-12-31T23:59:59" > }, > "buyer": { > "name": "Maria Santos", > "document": { > "type": "CPF", > "number": "90836247060" > }, > "email": "maria.santos@example.com" > }, > "amount": 5000, > "invoice": "test-charge-rejected-001", > "country": "BR", > "currency": "BRL", > "payment_method": "pix" > } > ``` > [accordion] Error Response - Processor Failure > > **Document**: 76145193026 > > **Expected Response**: 400 Bad Request > > **Expected Result**: Error message "Failed to send payin to processor" > > ```json theme={null} > { > "pix": { > "expire_date": "2025-12-31T23:59:59" > }, > "buyer": { > "name": "Carlos Oliveira", > "document": { > "type": "CPF", > "number": "76145193026" > }, > "email": "carlos.oliveira@example.com" > }, > "amount": 7500, > "invoice": "test-charge-error-001", > "country": "BR", > "currency": "BRL", > "payment_method": "pix" > } > ``` ## Charge Status Flow ### Successful Flow After creating a charge with a successful test document, the charge will go through: **1. Created** Initial status - Charge created and awaiting payment **2. Paid** Payment received from payer **3. Credited** Amount credited to your account ✓ ### Rejection Flow After creating a charge with the rejection test document, the charge will go through: **1. Created** Initial status - Charge created and awaiting payment **2. Rejected** Charge rejected with specific reason ✗ ## Testing Boleto Payments For boleto payments, the testing flow is different. After creating a boleto charge, you need to make an additional request to simulate the payment. ### Boleto Testing Process **1. Create boleto charge** Use the [Create Charge](/api-reference/cash-in/payin/create-charge) endpoint with `payment_method: "boleto"` **2. Get our\_number** Extract the `our_number` from the boleto creation response **3. Simulate payment** Make a POST request to `v1/payin/payments/pay/{our_number}` to simulate the boleto payment **4. Monitor status** The charge will follow: Created → Paid → Credited ### Boleto Payment Simulation To simulate a boleto payment and achieve the "Credited" status: ```bash theme={null} curl --location 'https://api.sandbox.wepayout.co/v1/payin/payments/pay/{our_number}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_TOKEN_HERE' \ --data-raw '{}' ``` **Replace `{our_number}`** with the actual `our_number` value from your boleto creation response. > [!NOTE] > > **Important**: This endpoint only simulates the status change (Created → Paid → Credited). It does not calculate interest, fines, or discounts configured in the boleto. ### Example - Complete Boleto Flow 1. **Create Boleto Charge**: ```json theme={null} { "payment_method": "boleto", "invoice": "YOUR-INVOICE-CODE", "currency": "BRL", "amount": 500, "country": "BR", "buyer": { "name": "Buyer Name", "email": "buyer@example.com", "document": { "type": "CPF", "number": "12345678901" }, "address": { "street": "Street Name", "number": "123", "complement": "Apt 456", "zipcode": "12345000", "city": "City Name", "district": "District Name", "state_code": "SP" } }, "originator_legal_entity": { "name": "Company Name", "document": "12345678901", "helpdesk": "company.com" }, "boleto": { "expire_date": "2025-12-31" } } ``` 2. **Extract our\_number** from response (example: `"our_number": "991763554947"`) 3. **Simulate Payment**: ```bash theme={null} curl --location 'https://api.sandbox.wepayout.co/v1/payin/payments/pay/991763554947' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_TOKEN_HERE' \ --data-raw '{}' ``` 4. **Expected Status Flow**: Created → Paid → Credited ## Important Notes > [card] Successful Documents > > **2 approved documents** > > Use these CPF numbers for charges that complete successfully > [card] Rejection Document > > **1 rejection document** > > Use this CPF to test rejection handling > [card] Error Document > > **1 error document** > > Use this CPF to test error responses > [!WARNING] > > **Production Environment**: Never use these test documents in production. They are only valid in the sandbox environment. ## Related Resources > [card] [Create Charge](/api-reference/cash-in/payin/create-charge) > > Create a new payin charge > [card] [Charge Status](/cash-in/status-flow) > > Understanding charge status flow > [card] [Rejection Reasons](/cash-in/rejection-reasons) > > Common rejection reasons and solutions > [card] [About Charges](/cash-in/about-charges) > > Learn about payin charges # About Payments Source: https://docs.wepayout.co/cash-out/about-payments Understanding the Payout solution and payment types # About payments In general, with our Payout product you can: * Create payout * Request payout cancelation * Issue proof of payout * Check your wallet balance * Consult status of payout * Filter, sort and export lists of payout * Filter, sort and export lists of bank statement ## Payments type: PIX and TED We process two types of payments for Pay Out: **PIX (Brazilian instant payment)** and **bank debit** and **TED (Brazilian electronic bank transfer)**. Payments which you choose for your processing flow are pre-configured by our team, and you are faced with different contexts. For example: ### INSTANT PAYMENT PROCESSING **Processing window**: 24/7, including weekends and holidays. **Confirmation**: D+1 **Payment information required**: bank details + bank code + branch + account and account digit. ### BANK DEBIT PAYMENT PROCESSING **Processing window**: on banking business hours only. **Confirmation**: D+1 **Payment information required**: bank details + bank code + branch + account and account digit. ## Type of operation for International Merchant There are two types of operations, you may consult our team to check which meets your company profile and contract. * **Usual Payments**: Payments related to goods and services. In this case you will be asked to inform the payer origin. * **Usual Payments**: Payments related to goods and services. In this case you will be asked to inform the payer origin and country information. ## PIX (Instant Payment) ### What is PIX? A Brazilian payment solution that settles funds transfers in a few seconds, ensuring the immediate availability of funds to the final beneficiary. ### PIX Key The PIX key is used to link the user's information to the bank transfer details, which may be a **CPF/CNPJ** (number), **PIX**, e-mail, cell phone or random key. Know more about PIX in the [Brazil central bank homepage](https://www.bcb.gov.br/estabilidadefinanceira/pix). ### Accepted PIX key formats The key type is identified from the value of `pix_key`, so the value must be sent exactly in one of the formats below, without masks, spaces or line breaks. A value that does not match any of them is refused when the request is sent (see [Rejection reasons](/cash-out/rejection-reasons#request-refused)). | Type | Format | Example | | - | - | - | | CPF | 11 digits, check digits validated | `46852919480` | | CNPJ | 14 characters: 12 digits or letters followed by 2 numeric check digits, check digits validated. Numeric and alphanumeric CNPJs are accepted | `00782322343339`, `NRP5LL11F9XV92` | | Phone | Brazilian mobile number in international format: `+55`, area code (DDD) without a leading zero, `9` and 8 more digits. **Exactly 14 characters** | `+5551966084315` | | E-mail | Valid e-mail address with **up to 77 characters** | `ana.2766c0@example.com` | | Random key | UUID v4 in lowercase, with hyphens (36 characters) | `26ab21ae-2778-4255-949c-30b1072bd529` | > [!WARNING] > > These values are refused: > > * CPF or CNPJ with punctuation, such as `468.529.194-80`. > * Phone without `+55` (`5551966084315`), landline numbers (`+555166084315`) or numbers from other countries. > * E-mail longer than 77 characters. > * Random key in uppercase (`26AB21AE-2778-4255-949C-30B1072BD529`). > [!NOTE] > > The examples on this page are randomly generated and do not belong to real people or companies. ## CPF and CNPJ The Cadastro de Pessoas Físicas (CPF, Portuguese for "Natural Persons Register") is the Brazilian individual taxpayer registry identification, since 1968 maintained by the Receita Federal do Brasil (Federal Revenue of Brazil). It is an 11-digit number, who pay taxes or take part, directly or indirectly, in activities that provide revenue for any of the dozens of different types of taxes. A CPF is 11 digits long, with nine base digits, and two digits at the end that are the result of an arithmetic operation on the first nine digits. The format of a CPF is: 731.001.94200. A CNPJ is also a taxpayer identification number, but it is used for businesses, real institutions. All businesses that are formed in Brazil must apply for a CNPJ, and it is the number at the time of formation. Foreign companies that wish to invest or own assets in Brazil must also have a CNPJ number. A CNPJ is 14 characters long: 12 base characters and two check digits at the end that are the result of an arithmetic formula over the base characters, making any typing mistake when entering the number lead to an invalid number. Here is an example of a CNPJ: XX.XXX.XXX/0001-XX. Since the Receita Federal started issuing alphanumeric CNPJs, the 12 base characters may be digits (`0-9`) or uppercase letters (`A-Z`); the two check digits are always numeric. Both formats are accepted. An alphanumeric CNPJ looks like this: 00.000.000/E08G-12. ## Brazilian Bank Account Information In Brazil there are two types of bank data, the pix key and the conventional data, which are composed of: All bank accounts in Brazil have the following information: * **Bank code**: this is the number with 3 characters that specifies which is the bank (each bank has its own code, for example 341 is Itaú) * **Bank branch**: this is the branch number (agência in Portuguese) for each account (in case that 4 numbers, the mandatory is only the 4 first, for example 1234-5) * **Bank type code**: Mandatory field to identify the type of bank account. It can be up to 2 characters normally, it depends on the bank * **Branch code**: code variation, just as the bank's branch number is the last number * **Account number**: mandatory number to identify the account. It can be up to 15 characters normally, it depends on the bank * **Account digit**: the check digit of the account, which is the character after the hyphen. For example, in account `1827167-1`, the account number is `1827167` and the account digit is `1`. The check digit is not part of the account number, so it is sent in its own field. Do not take the last digit of the account number as the check digit. * **Account type**: mandatory field to identify the account type. In the API, use `CHECKING` for checking accounts and `SAVINGS` for savings accounts. For payment accounts (contas de pagamento, as in digital banks), use `CHECKING`. Bank account number can be used for electronic payment or instant payment methods. The pix key is only available for instant payments (pix). ## Payment Flow > [card] PIX > > **Speed**: Instant (seconds) > > **Availability**: 24/7 > > **Payment Method**: PIX key or bank account > > **Confirmation**: Real-time > > **Best for**: Instant transfers, urgent payments > [card] TED > > **Speed**: D+1 > > **Availability**: Business hours > > **Payment Method**: Bank account details > > **Confirmation**: Next business day > > **Best for**: Traditional bank transfers, scheduled payments ## Use Cases > [accordion] Marketplace Payouts > > Pay sellers and partners for their sales or services on your marketplace platform. > [accordion] Freelancer Payments > > Process payments to freelancers and contractors for completed work. > [accordion] Supplier Payments > > Pay suppliers and vendors for goods and services. > [accordion] Refunds > > Process refunds to customers by sending money back to their accounts. > [accordion] Affiliate Commissions > > Pay commissions to affiliates and partners for referrals. > [accordion] Salary Payments > > Process salary and wage payments to employees. ## Getting Started **1. Create Your First Payment** Use the [Create Payment](/api-reference/cash-out/payout/create-payment) endpoint to send funds to a recipient. **2. Monitor Payment Status** Use the [Get Unique Payment](/api-reference/cash-out/payout/get-unique-payment) endpoint to check payment status. **3. List All Payments** Use the [List Payment](/api-reference/cash-out/payout/list-payment) endpoint to view all your payments with filters. **4. Set Up Webhooks** Configure [Callback Payment](/api-reference/cash-out/payout/callback-payment) to receive real-time payment notifications. ## Payment Requirements ### For PIX Payments > [!NOTE] > > **Required Information**: > > * Recipient name > * Recipient document (CPF or CNPJ) > * PIX key (CPF, CNPJ, email, phone, or random key) > * Amount ### For TED/Bank Transfer Payments > [!NOTE] > > **Required Information**: > > * Recipient name > * Recipient document (CPF or CNPJ) > * Bank code (3 digits) > * Branch number (agência) > * Account number > * Account digit > * Account type (checking or savings) > * Amount ## Best Practices > [card] Verify Recipient Data > > Always validate recipient information before processing payments to avoid errors. > [card] Check Balance > > Verify sufficient balance before creating payments to prevent failures. > [card] Use Webhooks > > Implement webhooks to receive real-time payment status updates. > [card] Track with External ID > > Use external\_id to track payments in your system and prevent duplicates. ## Payment Status Flow ```mermaid theme={null} graph TD A[Created] --> B[Processing] B --> C{Success?} C -->|Yes| D[Paid] C -->|No| E[Failed] B --> F[Rejected] A --> G[Cancelled] ``` ## Next Steps > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Learn how to create your first payout > [card] [Decode QR Code](/api-reference/cash-out/payout/decode-qr-code) > > Pay third-party PIX QR Codes > [card] [Create Transfer](/api-reference/cash-out/payout/create-transfer) > > Transfer between wallets > [card] [Get Balance](/api-reference/account/get-balance) > > Check your wallet balance > [card] [Callback Payment](/api-reference/cash-out/payout/callback-payment) > > Set up payment notifications > [card] [Get Statement](/api-reference/account/get-statement) > > View your account statement ## Additional Notes > [!NOTE] > > For international merchants, additional documentation and compliance requirements may apply. Contact our support team for more information. > [!WARNING] > > Payment processing times may vary depending on the recipient's bank and the payment method used. PIX payments are instant, while TED payments are processed on the next business day. > [!TIP] > > Use PIX for urgent payments and TED for scheduled or traditional bank transfers. Consider the recipient's preference and urgency when choosing the payment method. # Payment Methods Guide Source: https://docs.wepayout.co/cash-out/payment-methods-guide Understanding Bank Account Data vs PIX Key for payments # Payments Transfers via Bank Account Data ## Why Payments Transfers via Bank Account Data are More Advantageous Under the New Regulation? To justify our recommendation, let's first clarify the differences between bank account details, Pix key, and Pix payments: ### Bank Account Details These are the traditional details associated with a bank account, such as bank name, account number, and branch code. In Brazil, these details are used for transactions where the specific bank and account need to be specified directly. These are unique and non-transferable, similar to an address, and cannot be moved to another financial institution. ### Pix Key The Pix key functions as a nickname for bank account details, simplifying the process of receiving payments via the Pix system. The Pix key can be an identifier such as a CPF (tax ID), email, phone number, or a randomly generated key. It simplifies the process of receiving payments, eliminating the need to enter all bank account details. However, since the Pix key can be transferred between banks and accounts at any time, this flexibility requires revalidation, which may lead to transaction rejections if data mismatches occur. ### Payment via Pix Pix is Brazil's instant payment system, enabling transfers in just seconds, 24/7, even on holidays. Payments can be made in two ways: #### With a Pix Key The payment is directed to the Pix key registered by the user, such as CPF or email. #### With Bank Account Details The payment uses the user's traditional bank account information (branch and account number) but is still processed by the Pix system, maintaining the speed and immediacy of the payment. ## New Regulation and Compliance With Ordinance 615, the Ministry of Finance mandates that, to make deposits and receive prizes, users' accounts must: * Be registered with an institution authorized by the Central Bank of Brazil (BACEN) * Be linked to all transactions These requirements make the use of bank account details a safer and more advantageous choice, ensuring that the account is validated from the start and allowing payments to occur stably and in compliance with the Ministry of Finance guidelines, avoiding future complications in the payment flow. ## Pix Key Limitations Though convenient, the Pix key presents challenges for high-volume transactions: ### Limit on DICT Queries Frequent queries to the Directory of Transactional Account Identifiers (DICT) to validate Pix keys can reach a daily limit, leading to temporary blocks. ### Risk of Inconsistency When users change their Pix key to another bank, data mismatches may occur, impacting the continuity and security of payments. ## Advantages of Using Bank Account Details in Pix Payments With WEpayments, when making payments directly to registered bank account details, the institution validation occurs at the time the request is created. This way, the user is immediately informed if they need to review their registered account, eliminating potential rejections and ensuring a higher conversion rate and a better user experience in the long term. ### Reduced Rejections Since bank account details cannot be transferred between banks, there's no need for revalidation with each payment. This lowers the likelihood of transaction failures and rejections. ### Regulatory Compliance By using bank account details with the Pix system, the payment aligns more closely with regulations, as the registered account is verified and fixed. ## Conclusion With new regulatory requirements and Pix key limitations, we recommend using payments via bank account details through the Pix system. This approach maintains the speed and reliability of Pix while providing enhanced security and regulatory compliance, delivering a stable and reliable experience for the user. *** ## Comparison Table > [card] Bank Account Details > > **Advantages**: > > * Unique and non-transferable > * No revalidation needed > * Reduced rejections > * Regulatory compliance > * Validated at creation > > **Best for**: High-volume transactions, stable payments > [card] PIX Key > > **Advantages**: > > * Easy to remember > * Quick to use > * Flexible (can change banks) > > **Limitations**: > > * DICT query limits > * Risk of inconsistency > * Requires revalidation > > **Best for**: One-time payments, personal transfers ## Payment Method Comparison | Feature | Bank Account Details | PIX Key | | - | - | - | | **Transferable** | ❌ No | ✅ Yes | | **Revalidation Required** | ❌ No | ✅ Yes | | **DICT Query Limits** | ✅ Not affected | ❌ Can reach limits | | **Rejection Risk** | ✅ Lower | ⚠️ Higher | | **Regulatory Compliance** | ✅ Full compliance | ⚠️ Requires validation | | **Speed** | ⚡ Instant (via PIX) | ⚡ Instant | | **Availability** | 🕐 24/7 | 🕐 24/7 | | **Best Use Case** | High-volume, business | Personal, one-time | ## Regulatory Compliance > [!NOTE] > > **Ordinance 615**: The Ministry of Finance requires that user accounts be: > > 1. Registered with BACEN-authorized institutions > 2. Linked to all transactions > > Using bank account details ensures compliance from the start. > [!WARNING] > > **PIX Key Risks**: While convenient, PIX keys can be transferred between banks, requiring revalidation and potentially causing payment failures. ## Related Resources > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Create payments with bank account details > [card] [About Payments](/cash-out/about-payments) > > Learn about payment types > [card] [Rejection Reasons](/cash-out/rejection-reasons) > > Understand rejection codes > [card] [Decode QR Code](/api-reference/cash-out/payout/decode-qr-code) > > Process PIX QR Codes > [card] [Get Balance](/api-reference/account/get-balance) > > Check wallet balance # Payout Webhook Source: https://docs.wepayout.co/cash-out/payout-webhook Receive real-time notifications about payout status changes Webhooks allow you to receive automatic notifications about payout events in real-time. When a payout status changes, WEpayments will send a POST request to your registered webhook URL with the updated transaction data. ## How It Works 1. **Configure your notification URL** when creating the payout payment using the `notification_url` parameter 2. **Receive notifications** automatically when payout status changes 3. **Process the payload** containing the complete payout details 4. **Return a 200 OK** response to acknowledge receipt ## Setting Up Webhooks To receive webhook notifications for payout transactions, include the `notification_url` parameter when [creating a payment](/api-reference/cash-out/payout/create-payment): ```json theme={null} { "invoice": "ORDER-12345", "notification_url": "https://your-domain.com/webhooks/payout", "payment_method": "PIX", "amount": 100.00, "currency": "BRL", "country": "BR", "beneficiary": { ... } } ``` The notification URL is defined in the `notification_url` field in the request body when creating a payment. Each payment can have its own notification URL, allowing you to route notifications to different endpoints based on your needs. ## Webhook Payload When a payout status changes, you'll receive a POST request with the following data: ### Response Fields **id** `integer` Payout ID Example: `2322977` **invoice** `string` Payout invoice Example: `575e8327-f145-48ff-b207-737eef2d6f3f` **end\_to\_end** `string` Payout end-to-end Example: `END-TO-END-ID` **status** `object` Object that contains the current status of your payout. **Status Object** **id** `integer` Current status ID of your payout Example: `6` **name** `string` Name of the current status of your payout Example: `Canceled` **updated\_at** `string` Last update of your payout. Format: `` Example: `2024-09-25 15:55:18` **status\_detail** `object` This object is returned when the payout is canceled (status `6`). It provides more details on the reason for the cancellation. See [Rejection Reasons](/cash-out/rejection-reasons) for the list of codes. **Status Detail Object** **code** `string` Code that represents the reason for the cancellation Example: `WE0001` **detail** `string` Explanation of the reason for the cancellation Example: `The payment was made to an unregistered account` ## Example Payload ```json theme={null} { "id": 2322977, "invoice": "575e8327-f145-48ff-b207-737eef2d6f3f", "status": { "id": 6, "name": "Canceled" }, "updated_at": "2024-09-25 15:55:18", "status_detail": { "code": "WE0001", "detail": "The payment was made to an unregistered account" } } ``` ## Status Codes Common payout status codes: | Status ID | Status Name | Description | | - | - | - | | 7 | Awaiting | Payout has been created and is waiting to be processed | | 1 | Received | Payout has been received | | 2 | Processing | Payout is being processed | | 5 | In Review | Payout is under compliance review | | 8 | Processed | Payout was sent and is waiting for confirmation | | 3 | Paid | Payout has been paid successfully | | 4 | Rejected | Payout was rejected by the bank (TED only) | | 6 | Canceled | Payout was canceled. See `status_detail` for the reason | | 11 | Invalid data input | Data provided is invalid or insufficient | See [Payout Status Flow](/cash-out/status-flow) for detailed status information. ## Webhook Endpoint Requirements Your webhook endpoint must: * **Accept POST requests** - All webhook notifications are sent via POST * **Use HTTPS** - Only secure HTTPS URLs are accepted * **Return 200 OK** - Respond with a 200 status code within 5 seconds * **Be publicly accessible** - The endpoint must be reachable from the internet ## Retry Policy > [!NOTE] > > If your endpoint responds with a failure (status code different from 200), **15 retry attempts** will be made with a **5-minute delay** between each attempt to deliver the webhook notification. ## Best Practices > [!NOTE] > > **Always Respond 200 OK**: Your endpoint must respond with HTTP 200 to acknowledge receipt. Otherwise, WEpayments will retry sending the webhook. > [!WARNING] > > **Validate Webhook Signature**: In production, always validate the webhook signature to ensure it's from WEpayments. Register a webhook `secret` to receive the recommended HMAC-SHA256 signature in the `x-webhook-wp-signature` header — the API key based signature is deprecated. See [Webhook Signature Documentation](/concepts/webhooks) for details. > [!TIP] > > **Process Asynchronously**: Handle webhook processing asynchronously to respond quickly and avoid timeouts. > [!WARNING] > > If the API returns a **Canceled**, **Failed**, or **Rejected** status, a new invoice must be generated. These statuses indicate that the record has already been processed and persisted in our database, preventing any modifications or retries using the same identifier. > [!NOTE] > > **Re-submission Policy:** > INVALID\_DATA: You may resubmit the same payload in a new request only if the payment status is INVALID\_DATA. This status occurs when banking details are incorrect (provided validation is enabled for the merchant). > Other Statuses: All other statuses will trigger a duplication block if an invoice with the same data already exists. ## Related Resources > [card] [Status Flow](/cash-out/status-flow) > > Understand payout status lifecycle # Rejection Reasons Source: https://docs.wepayout.co/cash-out/rejection-reasons Understanding payout rejection codes and error messages # Rejection reasons payout A payout can be refused at two different moments: 1. **When the request is sent**: the API answers with an HTTP error and the payout is **not created**. See [Request refused](#request-refused). 2. **After the payout is created**: the API answers `201` with status `Awaiting` (7), and the payout is later **Canceled** (6) or **Rejected** (4) during processing (compliance checks, balance, limits, beneficiary data, Pix key or bank response). See [Payout canceled or rejected after creation](#payout-canceled-or-rejected-after-creation). > [!NOTE] > > This page describes the behavior of the [Create Payment](/api-reference/cash-out/payout/create-payment) endpoint (`POST /v2/payout/payments`). ## Request refused When the request is refused, no payout is created and you can fix the data and send the request again. | HTTP status | When it happens | | - | - | | `400` | The request could not be processed, for example the same `invoice` was sent again while the previous request is still being processed, or the bank account data is invalid. | | `401` | The access token is missing, invalid or expired. | | `403` / `404` | The merchant informed in `merchant_id` was not found, is disabled or is not available for your user. | | `422` | One or more fields are invalid. See [Validation errors](#validation-errors). | | `451` | The beneficiary account is not one of the accounts authorized for your account (only when this restriction is enabled for your account). | | `503` | The service is temporarily unavailable for scheduled maintenance. Retry after the time informed in the `Retry-After` header. | | `500` | Unexpected error. Try again later or contact support. | ### Validation errors Validation errors return HTTP `422` with the list of invalid fields in `errors`. Each field can have more than one message. ```json theme={null} { "message": "The given data was invalid.", "errors": { "beneficiary.document.number": ["The document provided is not a valid CPF."], "pix.pix_key": ["Pix key type not identified. Review the pix_key value."] } } ``` Besides the standard messages for required fields, formats and sizes, these are the most common validation errors: | Field | Message | What to do | | - | - | - | | `beneficiary.document.number` | The document provided is not a valid CPF. / CNPJ. | Check the beneficiary CPF or CNPJ. | | `pix.pix_key` | Pix key type not identified. Review the pix\_key value. | The value does not match any accepted format, for example a phone that is not a Brazilian mobile number with exactly 14 characters or an e-mail longer than 77 characters. See [Accepted PIX key formats](/cash-out/about-payments#accepted-pix-key-formats). | | `pix.pix_key` | The pix.pix key is not a valid cpf. / cnpj. | The Pix key looks like a CPF or CNPJ but the number is invalid. | | `pix.pix_key` | Token Bucket request limit exceeded. | The Pix key query limit was reached. Wait and try again. | | `invoice` | The invoice has already been taken. | Another payout already uses this `invoice` (only when unique invoice is enabled for your account). Use a new `invoice`. | | `payment_method` | The payment method informed is not enabled. | The payment method is not enabled for your account. Contact support. | | `beneficiary.document.type` / `pix.pix_key` | The transaction is restricted because legal entities are not allowed to place requests in this scenario. | Payouts to a CNPJ are not allowed for your account. | | `originator_legal_entity` | The provided originator is invalid, not approved, or not authorized for this merchant. | Check the originator data sent in the request. | | `markup` | Markup errors | Check the `markup` object. See [Submerchant markup](/markup/about-markup). | ## Payout canceled or rejected after creation After a payout is created, it can be **Canceled** (status `6`) during processing. When this happens, the [payout webhook](/cash-out/payout-webhook) includes the `status_detail` object with the reason: ```json theme={null} { "id": 123456, "invoice": "INV-0001", "status": { "id": 6, "name": "Canceled" }, "updated_at": "2026-09-30 10:15:00", "status_detail": { "code": "47", "detail": "Insufficient Balance" } } ``` * `status_detail.code` identifies the reason. Use this field in your integration. * `status_detail.detail` is a human-readable description, in the language configured for your user. The text may change, so **do not use it to implement rules**. The same description is returned in the `rejection_description` field when you [get the payout](/api-reference/cash-out/payout/get-unique-payment). > [!NOTE] > > TED payouts rejected by the beneficiary bank end with status **Rejected** (`4`). In this case, the reason is available in the `rejection_description` field. ### Rejection codes table #### Beneficiary and bank data | Code | Reason | What to do | | - | - | - | | `1` | Rejected by bank | The beneficiary bank rejected the payment. Check the beneficiary data. | | `2` | Invalid document or bank data | Check the beneficiary CPF/CNPJ and bank account data. | | `3` | Blocked account | The beneficiary account is blocked. Ask the beneficiary for another account. | | `4` | Divergent beneficiary | The account or Pix key does not belong to the informed document. Check the beneficiary data. | | `5` | Wrong bank account or branch | Check the branch and account number. | | `6` | Wrong bank code | Check the bank code or ISPB. | | `7` | Wrong bank branch | Check the branch number. | | `8` | Wrong bank account | Check the account number and digit. A common cause is sending the last digit of the account number as `account_digit` and leaving out the real check digit: for account `823250233-4`, send `account: "823250233"` and `account_digit: "4"`. | | `9` | Wrong name | Check the beneficiary name. | | `10` | Wrong bank details | Check the beneficiary bank data. | | `15` | Irregular CPF | The beneficiary CPF is irregular. | | `20` | Divergence in CPF/CNPJ information | The informed CPF/CNPJ does not match the account holder. | | `22` | Account closed | The beneficiary account is closed. Ask the beneficiary for another account. | | `29` | Beneficiary's bank does not allow payment type indicated | The beneficiary bank does not accept this payment type. | | `30` | Account does not allow payment type indicated | The beneficiary account does not accept this payment type (for example, salary accounts). | | `31` | Incorrect account type | Check the account type (checking, savings, payment or salary). | | `32` | Pix rejected by beneficiary bank | The beneficiary bank rejected the Pix. Check the beneficiary data or ask for another account. | #### Pix | Code | Reason | What to do | | - | - | - | | `17` | Invalid pix key | The Pix key does not exist or is invalid. Check the key with the beneficiary. | | `26` | Beneficiary's bank does not allow payment type indicated | The beneficiary bank does not support this Pix operation. | | `27` | DICT Quota Exceeded | The Pix key query limit was reached. Send the payout again later. | | `46` | Token Bucket request limit exceeded | The Pix key query limit was reached. Send the payout again later. | | `48` | Pix key entry blocked | The Pix key is blocked. Ask the beneficiary for another key. | | `53` | Failed to send to bank | The payment could not be sent to the bank. Send the payout again. | #### Compliance and antifraud | Code | Reason | | - | - | | `28` | Canceled by Compliance | | `33` | Canceled by Compliance. Tax number on OFAC list | | `34` | Canceled by Compliance. Tax number on INTERPOL list | | `35` | Canceled by Compliance. Tax number on ONU list | | `36` | Canceled by Compliance. Tax number on EUROPEAN list | | `37` | Canceled by Compliance. Tax number is disabled (deceased) | | `38` | Canceled by Compliance. Tax number is PEP (politically exposed person) | | `39` | Canceled by Compliance. Tax number blocked on RFB (Brazilian Federal Revenue Office) | | `40` | Canceled by Compliance. Canceled due to CPF restriction underage Brazilian law | | `41` | Canceled due to restriction age (over 80 years old) as per compliance policy | | `43` | Restricted by KYC | | `51` | Payment rejected after preventative review | | `52` | Transaction canceled. The recipient's document is irregular with the Federal Revenue Service or appears on international restrictive lists | | `54` | Transaction rejected. The payer's document is irregular with the Federal Revenue Service or appears on international restrictive lists | | `57` | Remitter's CPF is invalid or inactive at Receita Federal | | `58` | Unable to validate the remitter's document. | See [Compliance](#compliance) for more details. Compliance cancellations cannot be retried. #### Balance and limits | Code | Reason | What to do | | - | - | - | | `14` | The payment amount is above the allowed for the account type | Reduce the amount or use another beneficiary account. | | `18` | Value exceed the max amount | The amount is above the maximum allowed. Reduce the amount. | | `47` | Insufficient Balance | Check your balance with [Get Balance](/api-reference/account/get-balance) before sending the payout again. | | `49` | Transactional limit exceeded | The amount is above your transactional limit. Contact support to review your limits. | #### Account restrictions | Code | Reason | What to do | | - | - | - | | `WE0001` | The payment was made to an unregistered account | The beneficiary account is not one of the accounts authorized for your account. | | `WE0002` | The payment was made to an unauthorized institution | The beneficiary institution is not authorized for your account. | #### Other reasons | Code | Reason | What to do | | - | - | - | | `11` | Canceled due to duplicated invoice | Another payout with the same `invoice` already exists. | | `13` | Client request payment cancelation | The payout was canceled at your request or by a restriction configured for your account (for example, a blocked beneficiary). | | `16` | Cancelation requested by client | The payout was canceled at your request. | | `42` | Canceled due to external error | The payment could not be completed by the receiving institution or payment network. Check the beneficiary data and send the payout again, or contact support. | > [!TIP] > > A payout returned by the beneficiary after it was paid is not a rejection: it keeps the **Paid** status and receives a refund substatus. > [!NOTE] > > To check the list of rejection reasons for payin, please see the [Rejection reasons payin](/cash-in/rejection-reasons) page. ## Compliance Every payout goes through compliance checks. The beneficiary document is verified against restrictive lists and compliance policies: * **OFAC list** (Office of Foreign Assets Control): code `33` * **INTERPOL list**: code `34` * **UN list** (United Nations Security Council): code `35` * **European Union list**: code `36` * **Deceased persons** (document disabled): code `37` * **PEP list** (Politically Exposed Persons): code `38` * **Brazilian Federal Revenue** (document irregular or blocked): code `39` * **Age restrictions** (underage or over 80 years old): codes `40` and `41` * **KYC restrictions**: code `43` * **Other compliance restrictions**: code `28` * **Remitter CPF** (remittance payouts): code `57` when the CPF is not found or not active at the Brazilian Federal Revenue, and `58` when it cannot be validated Payouts can also be canceled after a preventative antifraud review (codes `51`, `52` and `54`). > [!NOTE] > > When the compliance check needs a manual review, the payout is not canceled: it goes to **In Review** (`5`) until the review is finished. See [Payout Status Flow](/cash-out/status-flow). ## Handling Rejection Errors **1. Identify the Error** If the request was refused, check the HTTP status and the `errors` object. If the payout was canceled after creation, check `status_detail.code` in the webhook. **2. Review the Description** Use the tables on this page to understand the reason for the rejection. **3. Take Corrective Action** Based on the error code, take appropriate action: * Check wallet balance * Verify recipient information * Review compliance requirements * Contact support if needed **4. Retry the Request** After correcting the issue, send a new payout request. Compliance cancellations cannot be retried. ## Common Scenarios > [card] Insufficient Balance > > **Code**: `47` > > **Solution**: Check wallet balance before creating payment. Use [Get Balance](/api-reference/account/get-balance) endpoint. > [card] Invalid Pix Key > > **Code**: `17` > > **Solution**: Verify the Pix key with the beneficiary before sending the payout again. > [card] Compliance Block > > **Codes**: `28`, `33` to `43` > > **Solution**: Recipient appears on restrictive lists (OFAC, PEP, etc.) or does not meet compliance policies. Cannot proceed with payment. > [card] Transactional Limit Exceeded > > **Code**: `49` > > **Solution**: Payment amount exceeds your transactional limit. Split into smaller payments or contact support to review your limits. ## Best Practices > [!NOTE] > > **Check Balance First**: Always verify wallet balance before attempting to create a payment to avoid rejection. > [!WARNING] > > **Validate Recipient Data**: Ensure recipient information is accurate and complete before processing payments. > [!TIP] > > **Handle Compliance Rejections**: Implement proper error handling for compliance-related rejections. These cannot be retried and require manual review. ## Related Resources > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Learn how to create payments with proper validation > [card] [About Payments](/cash-out/about-payments) > > Understand the Payout solution and payment types > [card] [Get Balance](/api-reference/account/get-balance) > > Check wallet balance before payments > [card] [Callback Payment](/api-reference/cash-out/payout/callback-payment) > > Receive payment status updates # Payout Status Flow Source: https://docs.wepayout.co/cash-out/status-flow Understanding the lifecycle of PIX and TED payout transactions # Payout Status Notification We will show the flow of payments for payout, regarding the status. > [!WARNING] > > Payments (payout) in final statuses: **PAID**, **CANCELED**, **REJECTED**, **INVALID\_DATA** can no longer be updated. ## Payout PIX and TED ```mermaid theme={null} graph TD A[AWAITING] --> B[RECEIVED] A --> C[CANCELED] B --> D[IN REVIEW] B --> E[RECEIVED] C --> F[Canceled by operator] D --> G[Payment in review compliance team] E --> H[The balance and compliance checks have been completed and the payment is ready to be processed] E --> I[PROCESSING] I --> J[The bank is processing the payment] J --> K[PROCESSED] K --> L[The bank has processed the payment] L --> M[REJECTED] L --> N[PAID] M --> O[Rejected by the bank or internal compliance rules] N --> P[The bank has confirmed the payment] F --> Q[SEND WEBHOOK] G --> Q O --> Q P --> Q Q --> R[Webhook sent] ``` ## Possible payment (payout) status | 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 insufficient (only available under client request). | > [!NOTE] > > You can check the reasons why our compliance team will reject a payment in our article [Rejection reasons payout](/cash-out/rejection-reasons). ## Status Details > [accordion] 7 - Awaiting > > **Initial Status** > > The first status when a payout is created. If the payment stays in this status for more than 1 minute, it means there is no balance in your account to make the payment. > > **Action**: Check your wallet balance using [Get Balance](/api-reference/account/get-balance). > > **Next possible statuses**: Received, Canceled > [accordion] 1 - Received > > **Payment Accepted** > > Payment received and stored in our database. The balance and compliance checks have been completed, and the payment is ready to be processed. > > **Next possible statuses**: Processing, In Review > [accordion] 2 - Processing > > **Being Processed** > > Payment sent for processing. The bank is processing the payment. > > **Next possible statuses**: Processed > [accordion] 5 - In Review > > **Compliance Review** > > Payment sent to our compliance team for review. This happens when additional verification is required. > > **Action**: Wait for compliance team review. This may take some time depending on the case. > > **Next possible statuses**: Processed, Rejected, Canceled > [accordion] 8 - Processed > > **Sent to Bank** > > Payments sent for processing and waiting confirmation from processor. The bank has processed the payment and is confirming the transaction. > > **Next possible statuses**: Paid, Rejected > [accordion] 3 - Paid > > **Final Status - Success** > > Payment made with success. The bank has confirmed the payment and funds have been transferred to the recipient. > > **This is the final success status**: > > * Funds have been transferred > * Webhook notification is sent > * Transaction is complete > > **Action**: No further action needed. Payment completed successfully. > [accordion] 4 - Rejected > > **Final Status - Bank Rejection** > > Payment rejected by the bank (only TED). This happens when the bank refuses to process the payment due to internal rules or invalid account information. > > **Common reasons**: > > * Invalid bank account details > * Account closed or blocked > * Bank internal policies > > **Action**: Review recipient information and create a new payment with corrected details. > [accordion] 6 - Canceled > > **Final Status - Canceled** > > Payment canceled by Merchant (TED or PIX) or Payment rejected by the bank (Only PIX). > > **Reasons**: > > * Manual cancellation by merchant > * PIX payment rejected by bank > * Compliance rejection > > **Action**: Check cancellation reason. If needed, create a new payment with corrected information. > [accordion] 11 - Invalid Data Input > > **Final Status - Invalid Data** > > Data provided invalid or insufficient (only available under client request). > > **Action**: Review all payment data and ensure all required fields are correctly filled. Create a new payment with valid data. ## Webhook Notifications > [!NOTE] > > Webhooks are sent only for **final statuses**: Paid, Rejected, Canceled ### When to Expect Webhooks > [tab] PIX > > **Fast Notifications** > > PIX webhooks are sent shortly after payment completion: > > * **Paid**: Within seconds to minutes after bank confirmation > * **Rejected**: Immediately if rejected by bank > * **Canceled**: Immediately after cancellation > > ```json theme={null} > { > "id": 54321, > "invoice": "PAYOUT-001", > "end_to_end": "END-TO-END-ID", > "status": { > "id": 3, > "name": "Paid" > }, > "updated_at": "2024-06-13T10:05:00.000000Z" > } > ``` > [tab] TED > > **Delayed Notifications** > > TED webhooks are sent after bank processing: > > * **Paid**: After bank confirmation (typically D+1) > * **Rejected**: After bank rejection (typically D+1) > * **Canceled**: Immediately after cancellation > > ```json theme={null} > { > "id": 54322, > "invoice": "PAYOUT-002", > "end_to_end": "END-TO-END-ID", > "status": { > "id": 3, > "name": "Paid" > }, > "updated_at": "2024-06-14T10:00:00.000000Z" > } > ``` ## Status Monitoring **1. Create Payment** Use [Create Payment](/api-reference/cash-out/payout/create-payment) to initiate a payout. Initial status: **Awaiting (7)** **2. Payment Accepted** System validates balance and compliance. Status changes to: **Received (1)** **3. Processing** Payment is sent to the bank for processing. Status changes to: **Processing (2)** → **Processed (8)** **4. Receive Webhook** Webhook notification is sent with final status. Final status: **Paid (3)**, **Rejected (4)**, or **Canceled (6)** ## Status Flow Diagram ### PIX Payment Flow ``` Awaiting (7) → Received (1) → Processing (2) → Processed (8) → Paid (3) ✓ → Rejected/Canceled (6) ✗ ``` ### TED Payment Flow ``` Awaiting (7) → Received (1) → Processing (2) → Processed (8) → Paid (3) ✓ → Rejected (4) ✗ ``` ### With Compliance Review ``` Awaiting (7) → Received (1) → In Review (5) → Processing (2) → Processed (8) → Paid (3) ✓ → Rejected/Canceled (6) ✗ ``` ## Related Resources > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Create PIX or TED payments > [card] [Get Payment](/api-reference/cash-out/payout/get-unique-payment) > > Check payment status > [card] [Payout Webhook](/cash-out/payout-webhook) > > Configure webhook notifications > [card] [Rejection Reasons](/cash-out/rejection-reasons) > > Understand rejection codes > [card] [About Payments](/cash-out/about-payments) > > Learn about payment types > [card] [Get Balance](/api-reference/account/get-balance) > > Check wallet balance ## Additional Notes > [!NOTE] > > For more information about webhook configuration and signature validation, check our article [Webhook Signature](/concepts/webhooks). > [!WARNING] > > Payments in **Awaiting** status for more than 1 minute indicate insufficient balance. Always check balance before creating payments. > [!TIP] > > Use the **In Review** status to inform users that their payment is under compliance review and may take additional time to process. # Test Documents Source: https://docs.wepayout.co/cash-out/test-documents Test documents for payout scenarios in sandbox environment ## Documents for Testing The result of the payout payment is linked to the beneficiary's document. Use the documents below to test different payment scenarios in the sandbox environment. ## PIX Key Payment For payments using **PIX key**, use one of the following CPF documents to ensure the payment is approved: | Document (CPF) | Status | Description | | - | - | - | | **58713371126** | Paid | Payment approved successfully | | **59730932395** | Paid | Payment approved successfully | | **78592315492** | Paid | Payment approved successfully | ### Example - PIX Key Payment ```json theme={null} { "payment_method": "PIX", "currency": "BRL", "country": "BR", "amount": 50.00, "invoice": "unique-invoice-id", "beneficiary": { "name": "João Silva", "document": { "type": "CPF", "number": "58713371126" } }, "pix": { "pix_key": "58713371126" } } ``` ## Bank Account Payment For payments using **bank account details**, use one of the following CPF documents to ensure the payment is approved: | Document (CPF) | Status | Description | | - | - | - | | **58713371126** | Paid | Payment approved successfully | | **59730932395** | Paid | Payment approved successfully | | **78592315492** | Paid | Payment approved successfully | | **78493353094** | Paid | Payment approved successfully | ### Example - Bank Account Payment ```json theme={null} { "payment_method": "PIX", "currency": "BRL", "country": "BR", "amount": 100.00, "invoice": "unique-invoice-id", "beneficiary": { "name": "Maria Santos", "document": { "type": "CPF", "number": "59730932395" } }, "pix": { "ispb": "18236120", "bank_branch": "0496", "account": "51659", "account_digit": "7", "account_type": "CHECKING" } } ``` ## Testing Flow **1. Choose payment method** Decide whether to test PIX key or bank account payment **2. Select test document** Choose one of the approved CPF documents from the tables above **3. Create payment** Use the [Create Payment](/api-reference/cash-out/payout/create-payment) endpoint with the test document **4. Monitor status** Check the payment status using webhooks or the [Get Payment](/api-reference/cash-out/payout/get-unique-payment) endpoint **5. Verify completion** Confirm the payment reaches **Paid** status (status\_id: 3) ## Best Practices > [!NOTE] > > **Sandbox Environment**: Always use test documents in the sandbox environment. These documents are specifically configured for testing purposes. > [!TIP] > > **Unique Invoice**: Always use a unique invoice ID for each payment to avoid duplicates and ensure proper tracking. ## Common Test Scenarios > [accordion] PIX Key - Successful Payment > > **Document**: 58713371126 > > **Payment Method**: PIX Key > > **Expected Result**: Payment approved and completed > > ```json theme={null} > { > "payment_method": "PIX", > "currency": "BRL", > "country": "BR", > "amount": 43.34, > "invoice": "test-pix-key-001", > "beneficiary": { > "name": "João Silva", > "document": { > "type": "CPF", > "number": "58713371126" > } > }, > "pix": { > "pix_key": "58713371126" > } > } > ``` > [accordion] Bank Account - Successful Payment > > **Document**: 59730932395 > > **Payment Method**: Bank Account Details > > **Expected Result**: Payment approved and completed > > ```json theme={null} > { > "payment_method": "PIX", > "currency": "BRL", > "country": "BR", > "amount": 150.00, > "invoice": "test-bank-account-001", > "beneficiary": { > "name": "Maria Santos", > "document": { > "type": "CPF", > "number": "59730932395" > } > }, > "pix": { > "ispb": "18236120", > "bank_branch": "0496", > "account": "51659", > "account_digit": "7", > "account_type": "CHECKING" > } > } > ``` ## Payment Status Flow After creating a payment with a test document, the payment will go through the following statuses: **1. Awaiting (7)** Initial status - Payment created and awaiting processing **2. Received (1)** Payment received and stored in the system **3. Processing (2)** Payment sent for processing **4. Processed (8)** Payment processed and waiting confirmation **5. Paid (3)** Payment completed successfully ✓ ## Important Notes > [card] PIX Key Documents > > **3 approved documents** > > Use these CPF numbers as PIX keys for successful payments > [card] Bank Account Documents > > **4 approved documents** > > Use these CPF numbers with any valid bank account details > [!WARNING] > > **Production Environment**: Never use these test documents in production. They are only valid in the sandbox environment. ## Related Resources > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Create a new payout payment > [card] [Payment Status](/cash-out/status-flow) > > Understanding payment status flow > [card] [Rejection Reasons](/cash-out/rejection-reasons) > > Common rejection reasons and solutions > [card] [About Payments](/cash-out/about-payments) > > Learn about payout payments # Error Codes Reference Source: https://docs.wepayout.co/concepts/error-codes Consolidated reference of HTTP status codes, rejection codes and status detail codes returned by the WEpayments API and webhooks # Error Codes Reference This page consolidates every error and rejection code the WEpayments API can return, in one place. Each code is machine-readable and stable: use the **code** in your integration logic and treat the description as informational only, since the text may change. > [!NOTE] > > Codes are returned at two different moments: > > 1. **When the request is sent** — the API answers with an HTTP error and nothing is created. You can fix the request and send it again. > 2. **After the transaction is created** — the API answers `201` and the transaction is later canceled or rejected during processing. The reason is delivered in the `status_detail` object of the [webhook](/concepts/webhooks) and in the transaction resource. ## HTTP status codes All endpoints use standard HTTP status codes. The table below applies to every product (payout, payin, account, data qualification). | HTTP status | Meaning | What to do | | - | - | - | | `200` / `201` | Request accepted. For payouts and charges, `201` means the transaction was created and will be processed asynchronously. | Track the final status by webhook or by querying the transaction. | | `400` | The request could not be processed: for example, a compliance restriction on a payin, the same `invoice` sent again while the previous request is still being processed, invalid bank account data, or an invalid or expired QR Code. | Check the `message` (and `data.code` for payin) and correct the request. | | `401` | The API key is missing, invalid or expired. | Check the `Authorization: Bearer` header. See [Authentication](/authentication). | | `403` / `404` | The resource (merchant, payment, charge, End-to-End ID) was not found, is disabled or is not available to your user. | Check the identifier and the account the API key belongs to. | | `409` | A conflicting operation is already running (for example, a bulk webhook resend job). | Wait for the running job to finish. | | `422` | One or more fields failed validation. The response lists every invalid field in `errors`. | Fix the fields listed and send the request again. | | `451` | The beneficiary account is not one of the accounts authorized for your account (only when this restriction is enabled). | Use an authorized beneficiary account or contact support. | | `503` | The service is temporarily unavailable for scheduled maintenance. | Retry after the time informed in the `Retry-After` header. | | `500` | Unexpected error. | Retry later. If the error persists, contact support with the request details. | ### Response formats > [tab] 422 Validation error > > Returned by every endpoint when a field is invalid. Each field can carry more than one message. > > ```json theme={null} > { > "message": "The given data was invalid.", > "errors": { > "beneficiary.document.number": ["The document provided is not a valid CPF."], > "pix.pix_key": ["Pix key type not identified. Review the pix_key value."] > } > } > ``` > [tab] 400 Compliance (payin) > > Returned by the payin endpoints when the payer document fails a compliance check. The `data.code` field carries the [payin restriction code](#payin-restriction-codes-request-time). > > ```json theme={null} > { > "status": false, > "message": "Compliance validation error", > "data": { > "code": "restriction_underage", > "description": "Rejected due to document restriction underage Brazilian law" > } > } > ``` > [tab] 401 Unauthorized > > ```json theme={null} > { > "error": { > "code": "unauthorized", > "message": "Invalid API key provided" > } > } > ``` > [tab] 422 with code (account endpoints) > > Account and webhook configuration endpoints return a `code` per field. > > ```json theme={null} > { > "message": "The given data was invalid.", > "errors": [ > { > "field": "event", > "code": "webhook_already_exists", > "params": [], > "message": "A webhook for this event already exists for this account." > } > ] > } > ``` ## Payout status detail codes Returned after a payout is created, when it ends as **Canceled** (`6`) or **Rejected** (`4`). The code is delivered in `status_detail.code` of the [payout webhook](/cash-out/payout-webhook) and the description in `rejection_description` when you [get the payout](/api-reference/cash-out/payout/get-unique-payment). ```json theme={null} { "id": 123456, "invoice": "INV-0001", "status": { "id": 6, "name": "Canceled" }, "updated_at": "2026-09-30 10:15:00", "status_detail": { "code": "47", "detail": "Insufficient Balance" } } ``` The **Retry** column tells you whether a new payout for the same beneficiary makes sense: * **After fix** — send a new payout after correcting the data indicated. * **Later** — the condition is temporary; send a new payout later. * **No** — compliance or policy decision; a new payout will be canceled again. ### Beneficiary and bank data | Code | Reason | Retry | What to do | | - | - | - | - | | `1` | Rejected by bank | After fix | The beneficiary bank rejected the payment. Check the beneficiary data. | | `2` | Invalid document or bank data | After fix | Check the beneficiary CPF/CNPJ and bank account data. | | `3` | Blocked account | After fix | The beneficiary account is blocked. Ask the beneficiary for another account. | | `4` | Divergent beneficiary | After fix | The account or Pix key does not belong to the informed document. See [CPF Mismatch](/features/cpf-mismatch). | | `5` | Wrong bank account or branch | After fix | Check the branch and account number. | | `6` | Wrong bank code | After fix | Check the bank code or ISPB. | | `7` | Wrong bank branch | After fix | Check the branch number. | | `8` | Wrong bank account | After fix | Check the account number and digit. | | `9` | Wrong name | After fix | Check the beneficiary name. | | `10` | Wrong bank details | After fix | Check the beneficiary bank data. | | `15` | Irregular CPF | No | The beneficiary CPF is irregular with the Federal Revenue. | | `20` | Divergence in CPF/CNPJ information | After fix | The informed CPF/CNPJ does not match the account holder. | | `22` | Account closed | After fix | The beneficiary account is closed. Ask the beneficiary for another account. | | `29` | Beneficiary's bank does not allow payment type indicated | After fix | Use another payment method or account. | | `30` | Account does not allow payment type indicated | After fix | The account does not accept this payment type (for example, salary accounts). | | `31` | Incorrect account type | After fix | Check the account type (checking, savings, payment or salary). | | `32` | Pix rejected by beneficiary bank | After fix | Check the beneficiary data or ask for another account. | ### Pix | Code | Reason | Retry | What to do | | - | - | - | - | | `17` | Invalid pix key | After fix | The Pix key does not exist or is invalid. Check the key with the beneficiary. | | `26` | Beneficiary's bank does not allow payment type indicated | After fix | The beneficiary bank does not support this Pix operation. | | `27` | DICT Quota Exceeded | Later | The Pix key query limit was reached. | | `46` | Token Bucket request limit exceeded | Later | The Pix key query limit was reached. | | `48` | Pix key entry blocked | After fix | The Pix key is blocked. Ask the beneficiary for another key. | | `53` | Failed to send to bank | Later | The payment could not be sent to the bank. | ### Compliance and antifraud | Code | Reason | Retry | | - | - | - | | `28` | Canceled by Compliance | No | | `33` | Canceled by Compliance. Tax number on OFAC list | No | | `34` | Canceled by Compliance. Tax number on INTERPOL list | No | | `35` | Canceled by Compliance. Tax number on UN list | No | | `36` | Canceled by Compliance. Tax number on European Union list | No | | `37` | Canceled by Compliance. Tax number is disabled (deceased) | No | | `38` | Canceled by Compliance. Tax number is PEP (politically exposed person) | No | | `39` | Canceled by Compliance. Tax number blocked on RFB (Brazilian Federal Revenue) | No | | `40` | Canceled due to CPF restriction: underage (Brazilian law) | No | | `41` | Canceled due to age restriction (over 80 years old) as per compliance policy | No | | `43` | Restricted by KYC | No | | `51` | Payment rejected after preventative review | No | | `52` | The recipient's document is irregular with the Federal Revenue Service or appears on international restrictive lists | No | | `54` | The payer's document is irregular with the Federal Revenue Service or appears on international restrictive lists | No | > [!NOTE] > > When a compliance check needs manual review, the payout is not canceled: it goes to **In Review** (`5`) until the review is finished. See [Payout Status Flow](/cash-out/status-flow). ### Balance and limits | Code | Reason | Retry | What to do | | - | - | - | - | | `14` | The payment amount is above the allowed for the account type | After fix | Reduce the amount or use another beneficiary account. | | `18` | Value exceed the max amount | After fix | The amount is above the maximum allowed. Reduce the amount. | | `47` | Insufficient Balance | Later | Check your balance with [Get Balance](/api-reference/account/get-balance) before sending the payout again. | | `49` | Transactional limit exceeded | After fix | Split into smaller payments or contact support to review your limits. | ### Account restrictions | Code | Reason | Retry | What to do | | - | - | - | - | | `WE0001` | The payment was made to an unregistered account | After fix | The beneficiary account is not one of the accounts authorized for your account. | | `WE0002` | The payment was made to an unauthorized institution | After fix | The beneficiary institution is not authorized for your account. | ### Duplicates and cancellations | Code | Reason | Retry | What to do | | - | - | - | - | | `11` | Canceled due to duplicated invoice | No | Another payout with the same `invoice` already exists. Query it by `invoice` instead of sending a new one. | | `13` | Client request payment cancelation | No | Canceled at your request or by a restriction configured for your account (for example, a blocked beneficiary). | | `16` | Cancelation requested by client | No | Canceled at your request. | | `42` | Canceled due to external error | Later | The receiving institution or payment network could not complete the payment. Check the beneficiary data and send the payout again, or contact support. | > [!TIP] > > A payout returned by the beneficiary after it was paid is not a rejection: it keeps the **Paid** status and receives a refund substatus. See [About Payments](/cash-out/about-payments). ## Payin restriction codes (request time) Returned with HTTP `400` and `message: "Compliance validation error"` when the payer document fails a compliance check at charge creation. The code is in `data.code`. | Code | Description | | - | - | | `restriction_overdue` | Rejected due to document restriction | | `restriction_underage` | Rejected due to document restriction: underage (Brazilian law) | | `restriction_deceased_holder` | Rejected due to document restriction: deceased holder | | `restriction_canceled` | Rejected due to document restriction: canceled document | | `restriction_unknown` | Rejected due to document restriction: unknown document | | `restriction_pending_regularization` | Rejected due to document restriction: pending regularization | | `restriction_suspended` | Rejected due to document restriction: suspended document | | `restriction_partners_and_ownership` | Rejected due to document restriction: partners and ownership | | `restriction_judicial_block` | Rejected due to document restriction: judicial block | | `restriction_cpf_irregular` | Rejected due to document restriction: irregular CPF | | `restriction_list_restrict` | Rejected due to document restriction: restrictive list | | `restriction_pep` | Rejected due to document restriction: PEP (Politically Exposed Person) | | `restriction_age_above_limit` | Rejected due to age restriction as per compliance policy | | `restriction_ofac` | Rejected due to document restriction on OFAC list | | `restriction_interpol` | Rejected due to document restriction on INTERPOL list | | `restriction_onu` | Rejected due to document restriction on UN list | | `restriction_euro` | Rejected due to document restriction on European Union list | Descriptions in Portuguese and handling guidance are available in [Rejection reasons payin](/cash-in/rejection-reasons). ## Payin status detail codes (webhook) Returned in `status_detail.code` of the [payin webhook](/cash-in/payin-webhook) when a Pix charge ends as **Rejected**. These codes are only sent when the "Account Mismatch" functionality is enabled for the merchant. | Code | Description | | - | - | | `reason_payer_divergence` | CPF mismatch: the payer is not the account holder | | `reason_payer_restriction_deceased_holder` | CPF restriction: deceased holder | | `reason_payer_restriction_canceled` | CPF restriction: canceled document | | `reason_payer_restriction_suspended` | CPF restriction: suspended document | | `reason_payer_pending_regularization` | CPF restriction: pending regularization | | `reason_payer_restriction_unknown` | CPF restriction: unknown document | | `gl_cpf_payer_restriction_underage` | CPF restriction: underage (Brazilian law) | | `reason_payer_restriction_age_above_limit` | Restriction: age above limit (over 80 years) | | `pending_challenge` | Pending challenge | | `reason_payer_restriction_receita` | CPF restriction (Tax Authority) | | `payer_restriction_high_risk` | CPF high risk | | `pending_review_manual` | Payment created; awaiting manual review | | `payer_restriction` | Rejected per compliance policy | | `reason_payer_restriction_pep` | PEP (Politically Exposed Person) | | `reason_payer_restriction_list_restrict` | CPF on restrictive list | | `reason_payer_restriction_cpf_irregular` | Irregular CPF | | `reason_payer_restriction_judicial_block` | Judicial block | | `reason_payer_restriction_partners_and_ownership` | Certified restriction (partners/ownership) | | `reason_payer_restriction_ofac` | CPF on OFAC list | | `reason_payer_restriction_interpol` | CPF on INTERPOL list | | `reason_payer_restriction_onu` | CPF on UN list | | `reason_payer_restriction_euro` | CPF on European Union restrictive list | | `reason_payer_restriction_pld` | KYC restriction | | `WE0001` | The payment was made from an unregistered account | | `WE0002` | The payment was made from an unauthorized institution | ## CPF Mismatch codes Returned by the [CPF Mismatch](/features/cpf-mismatch) feature when the document of the person paying or receiving does not match the account holder. | Code | Flow | Description | | - | - | - | | `RESTRICTION_PAYER_DIVERGENCE` | Payin | The payer's CPF does not match the account holder's CPF | | `BENEFICIARY_DIVERGENT` | Payout | The beneficiary's CPF does not match the registered holder's CPF (delivered as payout code `4`) | ## QR Code decode errors Returned by [Decode QR Code](/api-reference/cash-out/payout/decode-qr-code) and by [Create Payment](/api-reference/cash-out/payout/create-payment) with `payment_method: QRCODE`. | HTTP status | Message | Meaning | | - | - | - | | `400` | QR Code is invalid or expired | The EMV string could not be decoded or the charge has expired. | | `400` | QR Code doesn't have a valid status | Dynamic QR Codes are accepted only while the charge is active. | | `400` | (amount validation) | The QR Code amount is fixed (`is_amount_changeable: false`) and a different `amount` was sent. | | `404` | End to End ID not found | The `end_to_end_id` expired (5 minutes after decode) or was already used. Decode the QR Code again. | ## Account and webhook configuration codes Returned with HTTP `422` by the [webhook setup](/api-reference/account/webhook/webhook-setup) and related endpoints, in the `code` field of each error. | Code | Description | What to do | | - | - | - | | `webhook_already_exists` | A webhook for this event already exists for this account. | The event is already on another webhook of the account: remove it from that webhook with [Update](/api-reference/account/webhook/webhook-update) first. | | `webhook_url_already_exists` | A webhook with this URL already exists for this account. | Add the events to the existing webhook with [Update](/api-reference/account/webhook/webhook-update) instead of registering the URL again. | | `invalid_account` | The account does not exist or is not linked to your merchant. | Check the `account_id` sent. | | `unauthorized` | Invalid API key provided (HTTP `401`). | Check the API key. See [Authentication](/authentication). | ## Data Qualification statuses Statuses returned by the [Data Qualification](/api-reference/data-qualification/get-status) service, used to validate bank account data before sending payouts. | Status | Name | Description | | - | - | - | | `1` | Received | Request received and stored in our database | | `9` | Awaiting | Awaiting balance to be processed | | `999` | Processing | Validation sent for processing | | `5` | Valid data | The account data is valid | | `6` | Invalid data | The validation payment was rejected by the bank | | `7` | Validation not possible on this step | The account data provided cannot be validated | ## Handling errors in your integration **1. Request refused (HTTP 4xx/5xx)** Nothing was created. For `422`, read every field in `errors`; for `400` on payin, read `data.code`; for `503`, honor `Retry-After`. Fix and resend. **2. Transaction canceled or rejected after creation** Read `status_detail.code` from the webhook or the transaction resource. Use the tables above to decide whether to correct data and send a new transaction, wait, or stop. **3. Never retry on the description** Implement rules on the **code** only. Descriptions are localized and may change without notice. **4. Use a new invoice for retries** When a payout ends as Canceled, Failed or Rejected, a new `invoice` is required for the retry. The only exception is **Invalid Data** (`11`), which may be resubmitted with the same `invoice` after correcting the data. ## Related Resources > [card] [Rejection reasons payout](/cash-out/rejection-reasons) > > Detailed guidance and scenarios for each payout code > [card] [Rejection reasons payin](/cash-in/rejection-reasons) > > Payin compliance codes with descriptions in English and Portuguese > [card] [Payout Status Flow](/cash-out/status-flow) > > Lifecycle of a payout and its statuses > [card] [Webhooks](/concepts/webhooks) > > Signature, retries and payloads of the status notifications # Webhook Signature Source: https://docs.wepayout.co/concepts/webhooks Learn how to verify webhook signatures to ensure secure communication ## Overview Our webhooks include a signature in the request headers to ensure authenticity and integrity. This document explains the headers sent with every webhook, how the signature is generated and how you can verify it to ensure that the webhook payload was sent by our system. Webhooks are signed with the [HMAC-SHA256 signature](#hmac-sha256-signature) when your account has a webhook registered with a `secret` for the `payin`, `payout` or `kyc` event through the [Webhook Setup API](/api-reference/account/webhook/webhook-setup). > [!CAUTION] > > **⚠️ DEPRECATED: Legacy API key signature.** Webhooks delivered to the `notification_url` of a transaction (no webhook registered for the event), as well as Automatic PIX authorization and schedule webhooks, are still signed with the deprecated API key signature. It is **not recommended**, will be removed in the future and must not be used in new integrations — register a webhook with a `secret` and use the [HMAC-SHA256 signature](#hmac-sha256-signature) instead. > > If you still need to validate it, see [Legacy Webhook Signature (Deprecated)](/concepts/webhooks-legacy). > [!CAUTION] > > **The registered URL overrides the URL sent in each request.** Once a webhook is registered for the `payin` or `payout` event, **every** webhook of that event — status updates, refunds and Data Qualifications — is delivered to the registered URL, and the `notification_url` / `callback_url` sent when creating a transaction is **ignored**. For the `kyc` event, the registered URL replaces the KYC callback URL previously configured by our Customer Experience team. > > This also holds for subaccounts: a subaccount without its own webhook for an event uses its **main account's** webhook for that event — URL and `secret` —, so its `notification_url` is ignored as well. See [Subaccounts without a webhook](/api-reference/account/webhook/webhook-setup#subaccounts-without-a-webhook). > [!WARNING] > > Registering, updating or removing a webhook may take up to **5 minutes** to take effect. Until then, webhooks keep being delivered to the previous destination. ## Request Headers All webhooks are sent using the `POST` method with a JSON body. | Header | Value | Sent when | | - | - | - | | `Accept` | `application/json` | Always | | `Content-Type` | `application/json` | Always | | `User-Agent` | `WEpayments` | Always | | `x-webhook-wp-type` | Webhook type — see [values below](#webhook-types) | HMAC scheme (webhook registered for the event) | | `x-webhook-wp-timestamp` | Unix timestamp in **seconds** when the request was signed, e.g. `1790000000` | HMAC scheme (webhook registered for the event) | | `x-webhook-wp-signature` | 64-character lowercase hex HMAC-SHA256, **without** `Bearer` prefix | HMAC scheme, only when a `secret` is registered | > [!NOTE] > > A new `x-webhook-wp-timestamp` (and therefore a new signature) is generated on every delivery attempt, including retries. ### Webhook types Possible values of the `x-webhook-wp-type` header: | Value | Description | | - | - | | `payin-pix` | Status update of a Pix Payin (including Automatic Pix and Pix key credits) | | `payin-boleto` | Status update of a Boleto Payin | | `payin-credit-card` | Status update of a Credit Card Payin | | `payin-refund` | Refund of a received Pix Payin, requested by the merchant | | `payout-pix` | Status update of a Pix Payout | | `payout-ted` | Status update of a TED Payout | | `payout-qrcode` | Status update of a Pix QR Code Payout | | `payout-refund` | Pix Payout returned to the merchant | | `payout-customer-refund` | Status update of a customer refund (Reembolso) paid out to your customer | | `payout-data-qualification` | Status update of a Data Qualification | | `kyc` | Status update of a KYC — see [KYC Webhook](/api-reference/kyc/webhook) | ## HMAC-SHA256 Signature This is the recommended way to verify webhooks. ### Enabling it Register a webhook for the `payin`, `payout` and/or `kyc` event with a `secret` using the [Webhook Setup API](/api-reference/account/webhook/webhook-setup). The secret is only known to you and WEpayments — store it safely and never expose it on the client side. > [!NOTE] > > If a webhook is registered without a `secret`, the `x-webhook-wp-type` and `x-webhook-wp-timestamp` headers are still sent, but **no** `x-webhook-wp-signature` header is included. ### How the signature is generated ``` signature = hex( HMAC_SHA256( secret, raw_body + timestamp ) ) ``` Where: * `secret`: the secret you registered for the event, used as-is * `raw_body`: the **raw** HTTP request body, exactly as received * `timestamp`: the value of the `x-webhook-wp-timestamp` header * `raw_body` and `timestamp` are concatenated with **no separator** * The result is sent as lowercase hexadecimal in the `x-webhook-wp-signature` header > [!WARNING] > > Always compute the signature over the raw request body. Do not parse and re-serialize the JSON before verifying — the body may contain escaped characters (for example `\/` and `\uXXXX`) and any change in formatting or key order produces a different signature. ### Signature Verification 1. Read the `x-webhook-wp-timestamp` and `x-webhook-wp-signature` headers 2. Reject the request if the timestamp is too old (we recommend a tolerance of 5 minutes) to protect against replay attacks 3. Concatenate the raw request body with the timestamp 4. Compute the HMAC-SHA256 of the concatenated string using your secret, encoded as hexadecimal 5. Compare the result with the `x-webhook-wp-signature` header using a constant-time comparison If the signatures match, the webhook is verified as authentic. ```javascript Node.js theme={null} const crypto = require('crypto'); // rawBody must be the unparsed request body (e.g. express.raw({ type: 'application/json' })) function isValidWebhook(rawBody, headers, secret) { const timestamp = headers['x-webhook-wp-timestamp']; const signature = headers['x-webhook-wp-signature']; if (!timestamp || !signature) return false; if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; const expected = crypto .createHmac('sha256', secret) .update(rawBody + timestamp) .digest('hex'); return expected.length === signature.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature)); } ``` ```python Python theme={null} import hashlib import hmac import time def is_valid_webhook(raw_body: bytes, headers: dict, secret: str) -> bool: timestamp = headers.get("x-webhook-wp-timestamp") signature = headers.get("x-webhook-wp-signature") if not timestamp or not signature: return False if abs(time.time() - int(timestamp)) > 300: return False expected = hmac.new( secret.encode(), raw_body + timestamp.encode(), hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, signature) ``` ```php PHP theme={null} function isValidWebhook(string $rawBody, array $headers, string $secret): bool { $timestamp = $headers['x-webhook-wp-timestamp'] ?? null; $signature = $headers['x-webhook-wp-signature'] ?? null; if (! $timestamp || ! $signature) { return false; } if (abs(time() - (int) $timestamp) > 300) { return false; } $expected = hash_hmac('sha256', $rawBody . $timestamp, $secret); return hash_equals($expected, $signature); } // $rawBody = file_get_contents('php://input'); ``` ### Example For a webhook with the following data: * `secret` = `s3cr3t` * `x-webhook-wp-timestamp` = `1790000000` * Raw body = `{"id":123456,"status":{"id":3,"name":"Paid"},"notification_url":"https:\/\/example.com\/hook"}` **Signed string**: `{"id":123456,"status":{"id":3,"name":"Paid"},"notification_url":"https:\/\/example.com\/hook"}1790000000` **Expected `x-webhook-wp-signature`**: `7ca0961c467990b1c7f2bc53e7b789441ac1a1b5d4eddc6686d7c63de91bed8e` ### Rotating the secret Update the webhook with a new `secret` using the [Webhook Update API](/api-reference/account/webhook/webhook-update). Since changes may take up to 5 minutes to take effect, accept signatures computed with either the old or the new secret during this period. ## Related Resources > [card] [Webhook Setup](/api-reference/account/webhook/webhook-setup) > > Register a webhook URL and secret > [card] [KYC Webhook](/api-reference/kyc/webhook) > > Learn about KYC webhooks > [card] [Payin Callback](/api-reference/cash-in/payin/callback-charge) > > Payin webhook callback > [card] [Payout Callback](/api-reference/cash-out/payout/callback-payment) > > Payout webhook callback > [!NOTE] > > For any further questions or issues, please reach out to our support team. # About Source: https://docs.wepayout.co/credit-card/about-credit-card Learn how credit card charges work in WEPayments ## About credit-card charges Credit card charges are created as `PAYIN_CREATED` status. It goes from `PAYIN_CREATED` to `PAYIN_AWAITING_APPROVAL` when the checkout is requested. The checkout can be done in 2 different ways: * **Payments page** * **Transparent checkout** ## Payment page We provide you a simple payment page where you can view the instructions and request the payment. To use the page you will need the `key` field, which is returned when you create the charge. **For security reasons, it is not possible to open the payment page within an iframe.** The payment page url is: `https://page.goboleto.com/?hash={key}`. In sandbox environment the page url is: `https://page.sandbox.goboleto.com/?hash={key}`. After creating the charge, access to the credit-card checkout will be available via the URL of our payments page (in the description above). ### Required information for checkout The following additional information will be required to proceed with the checkout: * Credit card number * Cardholder Name * Address (that will be the payer' credit-card billing address) * Number of installments ## Transparent checkout The transparent checkout is a one-step process to create and pay the charge. There is some additional data to request a transparent checkout. When creating a credit-card charge, if the input `checkout` is present within the payload the charge will be created and processed. To get all required data to process a transparent checkout our SDK must be implemented. For further information, please read our documentation in the link below about Transparent Checkout and how to integrate our SDK: [Transparent Checkout](/credit-card/transparent-checkout) ## Transparent checkout with stored credit-card To perform the fast-checkout action, you only need to inform the `card_id` parameter inside the checkout object. This parameter refers to the saved credit card ID. To recover this parameter, just consult the list of cards saved for a customer. 2 endpoints are available for listing customer information and their saved cards: * List of customers for a given client: `/v1/payin/clients/{clientId}/customers` * List of cards for a given customer: `/v1/payin/customers/{customerId}/cards` If you inform the `card_id` parameter you MUST NOT inform `token` and `payment_method_id` parameters. ## Optional inputs (Payment page) During the checkout process, we provide the option to redirect the user to a custom success or failure page (according to the transaction status). Here follows the options for redirection: * `external_url.redirect_on_success`: The URL where the user will be redirected after a successful credit-card checkout. * `external_url.redirect_on_fail`: The URL where the user will be redirected after a failed credit-card checkout You can also provide a custom image URL to be displayed at our payment page by sending the `external_url.checkout_image_url` input. All 3 options are optional, and the user will be redirected to our default pages after the checkout if any of the redirect urls are present as well as the checkout image. ## Expiration date format The `expireDate` field is formatted as `YYYY-MM-DDTHH:SS`. Ex.: 2021-12-31T23:59:59 ## Possible charge statuses > [accordion] PAYIN\_CREATED > > The first status when the payin is created. > [accordion] PAYIN\_CANCELED > > Payin canceled due to expiration. > [accordion] PAYIN\_PAID > > Payin was paid. > [accordion] PAYIN\_CREDITED > > Payin was paid and the amount was credited on your wallet. > [accordion] PAYIN\_DROP\_REQUESTED > > Payin expiration requested. > [accordion] PAYIN\_AWAITING\_APPROVAL > > When the checkout is made, the charge goes from `PAYIN_CREATED` to `PAYIN_AWAITING_APPROVAL` (intermediate status) before the confirmation or any other payment final status occurs. > [accordion] PAYIN\_REJECTED > > The payment was rejected and could not be processed. ## Possible refund mode When creating a charge, you must know how the wallet values will be debited if a refund is requested. You can choose from the 3 options below: > [card] FULL\_REFUND\_CLIENT > > If none is informed, it will be selected by default. In this mode, the refund amount will be fully debited from the client wallet. > [card] FULL\_REFUND\_RECIPIENT > > In this mode, the refund amount will be fully debited from the sub-portfolio or sub-client informed in the split. In this mode, the refund will only be allowed if you have a maximum of 1 split. > [card] REFUND\_BY\_SPLIT > > In this mode, the refund amount will be debited proportionally as informed in the split and main wallet. In this mode, the refund will only be allowed if you have a maximum of 1 split. ## Security > [!WARNING] > > Regarding the safety of our customers, it is very important to emphasize that we DO NOT keep any information about credit-card and all credit-card information filled in the checkout page are only used once to confirm the transaction. For any further questions you can contact us through our customer service channels. ## Related Resources > [card] [Create Credit Card Charge](/api-reference/credit-card/create-charge) > > Create a new credit card charge > [card] [Webhook Signature](/concepts/webhooks) > > Learn how to verify webhook signatures > [card] [KYC Verification](/api-reference/kyc/list-kyc) > > Know Your Customer verification > [card] [FAQ](/faq) > > Frequently asked questions # Refund Webhook Source: https://docs.wepayout.co/credit-card/refund-webhook Receive real-time notifications about credit card refund status changes Refund webhooks allow you to receive automatic notifications whenever the status of a credit card refund changes. When you [create a refund](/api-reference/cash-in/refund/create-refund) for a credit card charge, WEpayments processes it asynchronously through the card processor and sends a POST request to your notification URL each time the refund reaches a new status. > [!NOTE] > > This webhook is **specific to refunds** and is separate from the [Credit Card Webhook](/credit-card/webhook), which notifies you about the charge (payin) status. A refund generates its own independent notifications. > [!WARNING] > > The payload format described on this page applies to **credit card** refunds. Refunds for other payment methods (such as Pix) may use a different payload structure — see [Create Refund](/api-reference/cash-in/refund/create-refund). ## How It Works 1. **Create a refund** for a credited credit card charge and provide a `notification_url` 2. **Receive notifications** automatically each time the refund status changes 3. **Process the payload** containing the refund details and amounts 4. **Return a 200 OK** response to acknowledge receipt > [!WARNING] > > A credit card charge can only be refunded if it is **credited to the wallet** and the refund is requested within **180 days** of the original payment. See [Create Refund](/api-reference/cash-in/refund/create-refund) for all refund rules. ## Setting Up the Refund Webhook To receive notifications, include the `notification_url` parameter when [creating the refund](/api-reference/cash-in/refund/create-refund): ```json theme={null} { "amount": 10000, "reason": "Customer requested cancellation", "notification_url": "https://your-domain.com/webhooks/credit-card-refund" } ``` Each refund can have its own notification URL, allowing you to route refund notifications to a dedicated endpoint. ## Refund Statuses You will receive a webhook for each of the following refund statuses: | Status ID | Status Name | Description | | - | - | - | | 2 | Requested | The refund has been requested and is being processed by the card processor. | | 4 | Paid | The refund has been successfully completed. | | 5 | Error | An error occurred while processing the refund. | ### Refund Status Flow **Success scenario:** ``` REQUESTED (2) → PAID (4) ✓ ``` **Error scenario:** ``` REQUESTED (2) → ERROR (5) ✗ ``` ## Webhook Payload When a credit card refund status changes, you'll receive a POST request with the following data: **id** `integer` Unique identifier of the refund. Example: `123` **payinId** `integer` ID of the credit card charge (payin) being refunded. Example: `456` **statusId** `integer` Current refund status ID (`2`, `4`, or `5`). **user** `object` User who created the refund. **User Object** **user.id** `integer` User ID. **user.name** `string` User name. **clientId** `integer` Your client ID in the WEpayments system. **amountCents** `integer` Amount of this refund, **in cents**. Example: `10000` **statuses** `array` History of all status changes for this refund. **Status History Item** **id** `integer` Status history record ID. **statusId** `integer` Status ID (`2`, `4`, or `5`). **status\_id** `integer` Same value as `statusId` (kept for backward compatibility). **name** `string` Status name (`Requested`, `Paid`, or `Error`). **notification** `integer` Whether this status change generated a notification (`1`) or not (`0`). **createdAt** `string` When this status was set (ISO 8601 format). **created\_at** `string` Same value as `createdAt` (kept for backward compatibility). **endToEndId** `string` End-to-end identifier. Used for Pix refunds; typically `null` for credit card refunds. **reason** `string` Reason provided when the refund was created. **walletErrorCode** `string` Error code returned by the processor when the refund fails (status `5`). `null` otherwise. **callbackUrl** `string` The notification URL configured for this refund. **createdAt** `string` Refund creation timestamp (ISO 8601 format). **updatedAt** `string` Timestamp of the last update (ISO 8601 format). ## Example Payloads ```json Requested theme={null} { "id": 123, "payinId": 456, "statusId": 2, "user": { "id": 789, "name": "João Silva" }, "clientId": 10, "amountCents": 10000, "statuses": [ { "id": 1, "statusId": 2, "status_id": 2, "name": "Requested", "notification": 1, "createdAt": "2026-02-19T12:34:56.000000Z", "created_at": "2026-02-19T12:34:56.000000Z" } ], "endToEndId": null, "reason": "Customer requested cancellation", "walletErrorCode": null, "callbackUrl": "https://your-domain.com/webhooks/credit-card-refund", "createdAt": "2026-02-19T12:34:56.000000Z", "updatedAt": "2026-02-19T12:34:56.000000Z" } ``` ```json Paid theme={null} { "id": 123, "payinId": 456, "statusId": 4, "user": { "id": 789, "name": "João Silva" }, "clientId": 10, "amountCents": 10000, "statuses": [ { "id": 1, "statusId": 2, "status_id": 2, "name": "Requested", "notification": 1, "createdAt": "2026-02-19T12:34:56.000000Z", "created_at": "2026-02-19T12:34:56.000000Z" }, { "id": 2, "statusId": 4, "status_id": 4, "name": "Paid", "notification": 1, "createdAt": "2026-02-19T12:36:22.000000Z", "created_at": "2026-02-19T12:36:22.000000Z" } ], "endToEndId": null, "reason": "Customer requested cancellation", "walletErrorCode": null, "callbackUrl": "https://your-domain.com/webhooks/credit-card-refund", "createdAt": "2026-02-19T12:34:56.000000Z", "updatedAt": "2026-02-19T12:36:22.000000Z" } ``` ```json Error theme={null} { "id": 123, "payinId": 456, "statusId": 5, "user": { "id": 789, "name": "João Silva" }, "clientId": 10, "amountCents": 10000, "statuses": [ { "id": 1, "statusId": 2, "status_id": 2, "name": "Requested", "notification": 1, "createdAt": "2026-02-19T12:34:56.000000Z", "created_at": "2026-02-19T12:34:56.000000Z" }, { "id": 2, "statusId": 5, "status_id": 5, "name": "Error", "notification": 1, "createdAt": "2026-02-19T12:35:10.000000Z", "created_at": "2026-02-19T12:35:10.000000Z" } ], "endToEndId": null, "reason": "Customer requested cancellation", "walletErrorCode": "PROCESSOR_ERROR", "callbackUrl": "https://your-domain.com/webhooks/credit-card-refund", "createdAt": "2026-02-19T12:34:56.000000Z", "updatedAt": "2026-02-19T12:35:10.000000Z" } ``` ## Authentication Credit card refund webhooks are delivered with the following headers: | Header | Value | | - | - | | `Accept` | `application/json` | | `Content-type` | `application/json` | | `User-Agent` | `WEpayments` | > [!NOTE] > > If you have configured a **custom authentication header** for your account (callback authentication key and value), it will be included in every refund webhook request. Contact our support team to set up a custom authentication header so you can validate that the request was sent by WEpayments. ## Webhook Endpoint Requirements Your webhook endpoint must: * **Accept POST requests** - All webhook notifications are sent via POST * **Use HTTPS** - Only secure HTTPS URLs are accepted * **Return 200 OK** - Respond with a 200 status code within 5 seconds * **Be publicly accessible** - The endpoint must be reachable from the internet ## Retry Policy > [!NOTE] > > If your endpoint responds with a status code other than 200, the notification will be retried up to **15 times**, with a 5-minute interval between attempts. ## Related Resources > [card] [Create Refund](/api-reference/cash-in/refund/create-refund) > > Create a refund for a credit card charge > [card] [Credit Card Webhook](/credit-card/webhook) > > Notifications about the charge status > [card] [About Credit Card](/credit-card/about-credit-card) > > How credit card charges and refund modes work > [card] [Create Credit Card Charge](/api-reference/credit-card/create-charge) > > Create a new credit card charge # Rejection Status Source: https://docs.wepayout.co/credit-card/rejection-status Understanding credit card rejection reasons and status codes During the transparent checkout (or regular checkout) some transactions might be rejected due to one or another issues regarding or not the credit card itself. Here follows a complete list of `status_details` that might occur. ## Incorrect credit card information: > [accordion] cc\_rejected\_bad\_filled\_card\_number > > **Incorrect card number** > > The card number provided is invalid or incorrect. > [accordion] cc\_rejected\_bad\_filled\_date > > **Incorrect card due date** > > The expiration date provided for the card is incorrect. > [accordion] cc\_rejected\_bad\_filled\_security\_code > > **Incorrect card security code** > > The CVV/security code provided is incorrect. > [accordion] cc\_rejected\_bad\_filled\_other > > **Any other card-related incorrect information** > > Other card information provided is incorrect or invalid. ## General credit card issues: > [accordion] cc\_rejected\_card\_disabled > > **Disabled credit card** > > The card has been disabled by the issuing bank and cannot be used for transactions. > [accordion] cc\_rejected\_card\_error > > **General credit card error** > > A general error occurred with the credit card processing. > [accordion] cc\_rejected\_insufficient\_amount > > **Credit card with insufficient funds** > > The card does not have sufficient available credit to complete the transaction. ## Internal issues: > [accordion] cc\_rejected\_card\_type\_not\_allowed > > **Credit card type not allowed** > > The type of credit card used is not accepted for this transaction. > [accordion] cc\_rejected\_duplicated\_payment > > **Duplicated payment for credit-card** > > A payment with the same details has already been processed. > [accordion] cc\_rejected\_invalid\_installments > > **Invalid number of installments selected** > > The number of installments chosen is not valid or not allowed. ## Internal due-diligence issues > [accordion] cc\_rejected\_blacklist > > **Credit card or holder signed as black list** > > The card or cardholder has been flagged and cannot proceed with transactions. > [accordion] cc\_rejected\_high\_risk > > **Credit card signed as high risk user to proceed with the transaction** > > The transaction has been flagged as high risk and cannot be processed. ## Fallback general errors: > [accordion] cc\_rejected\_other\_reason > > **Transaction rejected due to other reasons** > > The transaction was rejected for reasons not covered by the specific error codes above. > [accordion] cc\_rejected\_fallback > > **Fallback rejection (timeout, invalid payment information...)** > > The transaction was rejected due to timeout, invalid payment information, or other technical issues. > [accordion] bad\_request > > **Bad request during transaction** > > The request was malformed or contained invalid data. ## Best Practices > [!NOTE] > > **Handle Errors Gracefully**: Always provide clear error messages to your users based on the rejection status received. > [!WARNING] > > **Security**: Never store or log complete credit card information. Only use tokenized data. > [!TIP] > > **Retry Logic**: For certain errors like timeouts or temporary issues, implement a retry mechanism with appropriate delays. ## Common Solutions | Rejection Status | Recommended Action | | - | - | | **cc\_rejected\_bad\_filled\_**\* | Ask user to verify and re-enter card information | | **cc\_rejected\_card\_disabled** | Suggest user to contact their bank or use another card | | **cc\_rejected\_insufficient\_amount** | Suggest user to use another payment method or card | | **cc\_rejected\_duplicated\_payment** | Check if payment was already processed successfully | | **cc\_rejected\_high\_risk** | Contact support for manual review | | **cc\_rejected\_fallback** | Retry the transaction or contact support | ## Related Resources > [card] [Create Charge](/api-reference/credit-card/create-charge) > > Create a new credit card charge > [card] [Callback Charge](/api-reference/credit-card/callback-charge) > > Receive charge callbacks > [card] [Transparent Checkout](/credit-card/transparent-checkout) > > Learn about transparent checkout > [card] [About Credit Card](/credit-card/about-credit-card) > > Learn about credit card charges # Test Cards Source: https://docs.wepayout.co/credit-card/test-cards Everything you need to know about test cards # Test Cards Everything you need to know about test cards ## Cards for testing Here there are some testing cards. | Card | Number | CVC | Due Date | | - | - | - | - | | **Mastercard** | 5031 4332 1546 6351 | 123 | 11/25 | | **Visa** | 4235 6471 2692 5682 | 123 | 11/25 | | **Amex** | 3753 651551 54995 | 1234 | 11/25 | ## Documents for Scenarios The result of the payment of the charge is linked to the document, so it is important that when creating the charge the document is informed according to the expected result. | Document | Status | Reason | | - | - | - | | **34960826312** | confirmed | Approved payment. | | **45131731265** | rejected | Renew the card expiration date. | | **70814577358** | rejected | Review the data on the card. | | **38532397400** | rejected | Review the card security code. | | **10322493562** | rejected | Card disabled/ blocked. | | **58125837746** | rejected | You have already made a payment with this amount. If you need to pay again, use another card or other form of payment. | | **27943315625** | rejected | Insufficient balance (money) not this transaction. | | **87782371525** | rejected | The card issuing bank declined payment. Please use another card or contact your bank. | ## Retry In cases of status **Rejected** it is possible after the generation of the error, try to pay the charge again, but this made in order to approve the payment, re-approve a rejected payment, on mercadopago simply use a Pix card Visa. ### Example: | Card | Number | CVC | Due Date | | - | - | - | - | | **Visa** | 4235 6471 2692 5682 | 123 | 11/25 | ## Refund Charges that have been confirmed may be chargeback, the chargeback status is listed in the **Reason** entered in the chargeback request. | Reason | Scenario | | - | - | | **APRO** | Approved refund | | **REJECT** | rejected refund | | **CANCEL** | cancelled refund | Any other **Reason** informed from the mapped scenarios returns default error **fallback**. ## Testing Flow **1. Create a charge** Use the [Create Charge](/api-reference/credit-card/create-charge) endpoint with one of the test cards above **2. Use test document** Select a document from the scenarios table to test different payment outcomes **3. Process payment** Complete the checkout process using the test card and document **4. Verify status** Check the payment status based on the document used **5. Test retry (optional)** For rejected payments, retry with the Visa test card to approve **6. Test refund (optional)** For confirmed payments, test the refund flow with different reasons ## Best Practices > [!NOTE] > > **Sandbox Environment**: Always use test cards in the sandbox environment. Never use real card numbers for testing. > [!WARNING] > > **Document Matching**: The payment result is directly linked to the document (CPF/CNPJ) used. Make sure to use the correct document for the scenario you want to test. > [!TIP] > > **Complete Testing**: Test all scenarios including approved, rejected, retry, and refund flows to ensure your integration handles all cases properly. ## Common Test Scenarios > [accordion] Successful Payment > > **Document**: 34960826312 > > **Expected Result**: Payment confirmed and approved > > Use this scenario to test the happy path of your integration. > [accordion] Expired Card > > **Document**: 45131731265 > > **Expected Result**: Payment rejected - "Renew the card expiration date" > > Test how your application handles expired card errors. > [accordion] Insufficient Funds > > **Document**: 27943315625 > > **Expected Result**: Payment rejected - "Insufficient balance" > > Test how your application handles insufficient funds scenarios. > [accordion] Duplicate Payment > > **Document**: 58125837746 > > **Expected Result**: Payment rejected - "You have already made a payment with this amount" > > Test duplicate payment detection. > [accordion] Bank Declined > > **Document**: 87782371525 > > **Expected Result**: Payment rejected - "The card issuing bank declined payment" > > Test how your application handles bank-side rejections. ## Refund Testing To test refunds, first create a successful payment using document **34960826312**, then request a refund with one of the following reasons: > [card] APRO > > **Approved refund** > > Refund will be processed successfully > [card] REJECT > > **Rejected refund** > > Refund will be rejected > [card] CANCEL > > **Cancelled refund** > > Refund will be cancelled ## Related Resources > [card] [Create Charge](/api-reference/credit-card/create-charge) > > Create a new credit card charge > [card] [Rejection Status](/credit-card/rejection-status) > > Understanding rejection reasons > [card] [Transparent Checkout](/credit-card/transparent-checkout) > > Learn about transparent checkout > [card] [About Credit Card](/credit-card/about-credit-card) > > Learn about credit card charges # Transparent Checkout Source: https://docs.wepayout.co/credit-card/transparent-checkout Everything you need to know about our transparent checkout ## Integration Before starting the integration, it is necessary to keep in mind that, as this is a delicate operation involving sensitive data from an end user, it is necessary that your development and production environment is secure and has an https certificate. We recommend installing and using the ngrok CLI. ## Importing the SDK The first step to import the SDK is to check your integration environment: > [card] Development (Sandbox) > > For development use the sandbox SDK through the URL below. > > ``` > https://sdk.sandbox.wepayments.com.br/v1 > ``` > [card] Production > > For the production environment use the production SDK through the URL below. > > ``` > https://sdk.wepayments.com.br/v1 > ``` To import the transparent checkout SDK, you need to add the following code block to the head of your HTML. ```html theme={null} ... ... ``` ## Initializing the SDK The SDK can be initialized in 2 ways: manually or automatically. ### Initialize manually To manually initialize the SDK, you need to have a `publicKey`, this way the transparent checkout SDK will have the necessary configurations for your merchant. Your `publicKey` is visible within the payin settings view in your dashboard. With your key in hand, you now need to instantiate the SDK as follows: ```javascript theme={null} const sdk = WEPayin.init({ publicKey: "YOUR_PUBLIC_KEY", }); ``` ### Initialize automatically To automatically initialize the SDK, you need to include the `window.autoInitWeSdk` instruction before including the script on the page, as in the example: ```html theme={null} ... ... ``` With this, the SDK will be instantiated in the global variable `window.wesdk`. > [!NOTE] > > It is also necessary to whitelist, in your dashboard, the domain of the page where the SDK is being included. To do this, access **Charges > SDK Management**. ## Retrieve installments With the SDK instantiated, we now have control over the `installments` method, where we can retrieve data related to the installments that the customer can make the payment. To obtain this data, we must send to the SDK the total amount of the payment that the customer wants to make (in cents) and also the first six digits of the customer's card number, this number is called BIN. ### Payload ```javascript theme={null} const installments = await sdk.installments({ amountInCents: 100000, bin: "533278", }); ``` ### Parameters | Parameter | Type | Description | | - | - | - | | **amountInCents** | `number` \| `string` | Total amount in cents of the charge (Required) | | **bin** | `string` | First six digits of the credit card (Required) | ### Response The `installments` method used is a Promise that returns the following object, according to your configured number of installments: ```json theme={null} { "installments": [ { "installmentsNumber": 1, "installmentsAmountInCents": 100000, "installmentsTotalAmountInCents": 100000, "recommendedMessage": "1 parcela de R$ 1.000,00 (R$ 1.000,00)" }, { "installmentsNumber": 2, "installmentsAmountInCents": 50000, "installmentsTotalAmountInCents": 100000, "recommendedMessage": "2 parcelas de R$ 500,00 (R$ 1.000,00)" } ], "issuer": { "name": "Visa", "thumbnail": "http://logos.com/visa.png", "paymentMethodId": "visa" } } ``` ## Generate card token > [!WARNING] > > As informed at the beginning of the integration, the SSL certificate is necessary to operate. As this is a delicate operation involving sensitive data from an end user, it is necessary that your development and production environment is secure and has an https certificate. With SSL configured, we can start tokenizing the credit card data. For this, it is necessary to call the `tokenize` method passing its required parameters about the customer's card data. ### Payload ```javascript theme={null} const cardToken = await sdk.tokenize({ cardNumber: "5031433215406351", cardholderName: "CARDHOLDER NAME", cardExpirationMonth: "11", cardExpirationYear: "2025", securityCode: "123", identificationType: "CPF", identificationNumber: "53595590040", }); ``` ### Parameters | Param | Type | Description | | - | - | - | | **cardNumber** | `string` | Credit card number (16-19) - Required | | **cardholderName** | `string` | Cardholder name - Required | | **cardExpirationMonth** | `string` | Expiration month (MM) - Required | | **cardExpirationYear** | `string` | Expiration year (YY - YYYY) - Required | | **securityCode** | `string` | Security code number (3-4) - Required | | **identificationType** | `string` | Document type (CPF - CNPJ) - Required | | **identificationNumber** | `string` | Document number - Required | ### Response The `tokenize` method used is a Promise that returns the following object: ```json theme={null} { "token": "8e832a8bd0b896fd203fb33b13a4c601", "expirationMonth": 11, "expirationYear": 2025, "firstSixDigits": "503143", "lastFourDigits": "6351", "cardholder": { "identification": { "number": "12345678912", "type": "CPF" }, "name": "CARDHOLDER NAME" } } ``` With the data finally tokenized, we can now start the process of creating and paying the charge, which will occur simultaneously through a single call to the WEpayments API. ## Checkout With the credit card token, the number of installments that will be paid and the other data related to the charge, we can start the checkout. Through the endpoint below that is currently used to create charges, a new object called `checkout` will now be passed in its payload. If this object is filled in, at the time of creating the charge, its payment will also be made. **Endpoint**: `POST /v1/payin/payments/credit-card` ### Payload ```json theme={null} { "title": { "expireDate": "2023-03-16T18:46:11", "amountInCents": 100000, "instructions": "Payin instructions" }, "buyer": { "email": "buyer@email.com", "name": "Buyer Name", "document": { "type": "CPF", "number": "53595590040" }, "address": {} }, "statement_descriptor": "merchant_descriptor", "clientId": 123, "external_urls": {}, "product_info": [ { "title": "Product title", "category_id": "1", "id": "1", "quantity": "1", "unit_price": "12300", "description": "Product description" } ], "sender": { "name": "", "document": "", "helpdesk": "merchant.com" }, "checkout": { "token": "058f00af2efbadfbc85dddb532cf19d0", "installments": 2, "payment_method_id": "master", "payer_name": "Payer Name", "payer_phone": "11999999999", "payer_address": { "zip_code": "01311000", "street_name": "Avenida Paulista", "street_number": "123" } } } ``` > [!TIP] > > More details about the required fields and types of values to be sent to this endpoint in our [OpenAPI](/api-reference/credit-card/create-charge). ### Response After sending the data, the API will then return the response with the payment status at the time of completion of the request, as in the example below. ```json theme={null} { "id": 1234, "key": "4d81e367c4ba0r07e3cb2ag4b1bbfe1f5bdcf15a5c74989a4bfea9034f9a60x6", "clientId": 123, "subscriptionId": null, "clientName": "WE Payments - Credit Card", "senderName": null, "senderDocument": null, "senderHelpdesk": "merchant.com", "buyerName": "Buyer Name", "buyerDocument": "53595590040", "buyerEmail": "buyer@email.com", "customNumber": null, "ourNumber": null, "digitableLine": null, "barCodeNumber": null, "status": { "id": 6, "name": "Aguardando Aprovação" }, "sender": { "name": null, "helpdesk": null, "document": null }, "typePayin": "credit-card", "instructions": "", "amountCents": 100000, "paidAmountCents": null, "paidAt": null, "expiresAt": "2023-03-16 18:46:11", "createdAt": "2023-03-15T15:01:23.000000Z", "fine": null, "discount": null, "statusHistory": [ { "status": { "id": 1, "name": "Criado" }, "id": 9557, "updatedAt": "2023-03-15T15:01:23.000000Z" }, { "status": { "id": 6, "name": "Aguardando Aprovação" }, "id": 9558, "updatedAt": "2023-03-15T15:01:23.000000Z" } ], "refundMode": "FULL_REFUND_CLIENT", "refundAmountCents": 0, "payinRefunds": [] } ``` > [!NOTE] > > After this request has been completed, it is possible to check the status of the charge through a GET method at the following endpoint - `/v1/payin/payments/credit-card/{key}/status` - Passing as `key` the key of the charge created and returned in the Response above. ## Related Resources > [card] [Create Charge](/api-reference/credit-card/create-charge) > > Create a new credit card charge > [card] [Callback Charge](/api-reference/credit-card/callback-charge) > > Receive charge callbacks > [card] [About Credit Card](/credit-card/about-credit-card) > > Learn about credit card charges > [card] [FAQ](/faq) > > Frequently asked questions # Credit Card Webhook Source: https://docs.wepayout.co/credit-card/webhook Receive real-time notifications about credit card transaction status changes Webhooks allow you to receive automatic notifications about credit card transaction events in real-time. When a transaction status changes, WEpayments will send a POST request to your registered webhook URL with the updated transaction data. ## How It Works 1. **Configure your callback URL** when creating the credit card charge using the `callbackUrl` parameter 2. **Receive notifications** automatically when transaction status changes 3. **Process the payload** containing the complete transaction details 4. **Return a 200 OK** response to acknowledge receipt ## Setting Up Webhooks To receive webhook notifications for credit card transactions, include the `callbackUrl` parameter when [creating a charge](/api-reference/credit-card/create-charge): ```json theme={null} { "callbackUrl": "https://your-domain.com/webhooks/credit-card", "customNumber": "ORDER-12345", "title": { "expireDate": "2024-12-31T23:59:59", "amountInCents": 10000, "instructions": "Payment for order #12345" }, "buyer": { ... }, "sender": { ... } } ``` Each charge can have its own callback URL, allowing you to route notifications to different endpoints based on your needs. ## Webhook Payload When a credit card transaction status changes, you'll receive a POST request with the following data: ### Response Fields **id** `string` Unique charge identifier **key** `string` Unique key for payment page access **clientId** `integer` Your client ID in the WEpayments system **clientName** `string` Your registered company name **buyerName** `string` Name of the customer making the purchase **buyerDocument** `string` Customer's document number (CPF/CNPJ) **buyerEmail** `string` Customer's email address **customNumber** `string` Your custom reference number for this transaction **ourNumber** `integer` WEpayments internal transaction number **status** `object` Current transaction status **status properties** **status.id** `integer` Status ID **status.name** `string` Status name (e.g., "Created", "Paid", "Rejected") **typePayin** `string` Payment method type - will be `"credit-card"` for credit card transactions **amountCents** `integer` Transaction amount in cents **paidAmountCents** `integer` Amount actually paid in cents (null if not yet paid) **paidAt** `string` Timestamp when payment was confirmed (ISO 8601 format) **expiresAt** `string` Transaction expiration timestamp (ISO 8601 format) **createdAt** `string` Transaction creation timestamp (ISO 8601 format) **statusHistory** `array` Array of status changes with timestamps **refundMode** `string` Refund configuration mode **refundAmountCents** `integer` Total amount refunded in cents **payinRefunds** `array` Array of refund records if any refunds were processed **payin\_substatus** `string` Additional status information if applicable ## Example Payload ```json theme={null} { "id": "28018", "key": "e1ebf9d914174902a76a5af436f091d09cca0b1e9ad8984b5dcdfeead67ce6b8", "clientId": 1, "clientName": "Your Company", "buyerName": "Maria da Silva", "buyerDocument": "34960826312", "buyerEmail": "buyer-email@wepayments.com.br", "customNumber": "YOUR-CODE1234", "ourNumber": 17530, "status": { "id": 2, "name": "Paid" }, "typePayin": "credit-card", "amountCents": 8652, "paidAmountCents": 8652, "paidAt": "2024-02-21T19:20:00.000000Z", "expiresAt": "2024-12-31T23:59:59", "createdAt": "2024-02-21T19:15:00.000000Z", "statusHistory": [ { "status": { "id": 1, "name": "Created" }, "updatedAt": "2024-02-21T19:15:04.000000Z" }, { "status": { "id": 2, "name": "Paid" }, "updatedAt": "2024-02-21T19:20:15.000000Z" } ], "refundMode": "FULL_REFUND_CLIENT", "refundAmountCents": 0, "payinRefunds": [], "payin_substatus": null } ``` ## Webhook Endpoint Requirements Your webhook endpoint must: * **Accept POST requests** - All webhook notifications are sent via POST * **Use HTTPS** - Only secure HTTPS URLs are accepted * **Return 200 OK** - Respond with a 200 status code within 5 seconds * **Be publicly accessible** - The endpoint must be reachable from the internet ## Common Status Updates You'll receive webhook notifications for these status changes: * **Created** → Transaction initiated * **Paid** → Payment successfully processed * **Rejected** → Payment declined (see [Rejection Status](/credit-card/rejection-status) for details) * **Refunded** → Payment refunded to customer * **Canceled** → Transaction canceled ## Related Resources > [card] [Create Charge](/api-reference/credit-card/create-charge) > > Create a new credit card charge > [card] [Rejection Status](/credit-card/rejection-status) > > Understanding rejection reasons > [card] [Test Cards](/credit-card/test-cards) > > Test cards for development # FAQ Source: https://docs.wepayout.co/faq Frequently asked questions about WEPayments API # Frequent answers and questions > [accordion] What is the final status for Payin? > > **CREDITED** is the final status. The difference between PAID and CREDITED is that CREDITED represents when the value is available for withdrawal. > [accordion] What is the final status for Payout? > > **PAID** is the final status. > [accordion] How do we change the status of each transaction during tests? > > The transactions will change status automatically, this should take up to 5 minutes to complete. > > To simulate different scenarios and test specific statuses, use the test scenarios available: > > * **Credit Card**: See [Test Cards](/credit-card/test-cards) for documents that trigger different payment statuses > * **Sandbox Environment**: Use to test without affecting production > [accordion] Does Pix have any chargebacks? What is the timeframe for chargebacks related to Pix? > > Pix does not have a chargeback. However, the receiving merchant may issue a refund to the payer within 90 days after the original payment. > [accordion] Are there intermediate statuses for transactions? > > Yes, transactions go through multiple intermediate statuses before reaching their final state. The time to reach the final status varies depending on the payment method and processing conditions. > > For detailed information about all possible statuses and their flows: > > * **Payin**: See [Payin Status Flow](/cash-in/status-flow) > * **Payout**: See [Payout Status Flow](/cash-out/status-flow) > > Note: When you create a transaction, the first status won't send a webhook signal. Webhooks are sent only after status changes occur. > [accordion] What are the possible PIX keys? > > A Brazilian citizen with a bank account can register Pix keys using a CPF/CNPJ number, mobile number, e-mail address, or a random key. > > However, merchant accounts at WE currently support only the random Pix key for receiving funds. > [accordion] How do I get my API keys? > > You can generate your own API key directly in the dashboard. Check the instructions here: > > [How to create an API key](https://support.wepayments.com.br/support/legal/api-authentication) > > For additional assistance, contact the Integration Team at **[integration@wepayments.com.br](mailto:integration@wepayments.com.br)**. > [accordion] What's the difference between Sandbox and Production? > > * **Sandbox**: Testing environment where you can test integrations without processing real transactions > * **Production**: Live environment where real payments are processed > > Each environment has its own API keys and URLs. > [accordion] How do I verify webhook signatures? > > Register a webhook with a `secret` using the [Webhook Setup API](/api-reference/account/webhook/webhook-setup). Payin, Payout and KYC webhooks will then include an `x-webhook-wp-signature` header with the HMAC-SHA256 of the raw request body concatenated with the `x-webhook-wp-timestamp` header, using your secret as key. The legacy SHA-256 signature based on your API key is deprecated and not recommended for new integrations. See the [Webhook Signature](/concepts/webhooks) documentation for detailed examples. > [accordion] What payment methods are supported? > > WEPayments supports: > > * **PIX**: Instant payments > * **Bank Transfer**: TED/DOC transfers > * **Credit/Debit Cards**: Major card brands > * **Boleto**: Brazilian bank slip > [accordion] How long does it take for a PIX payment to be processed? > > PIX payments are processed instantly. The status change should occur within seconds to a few minutes. > [accordion] Can I cancel a payment after it's been created? > > * **Payin**: Can be canceled before payment is completed > * **Payout**: Cancellation depends on the payment status. Contact support for assistance. > [accordion] What is KYC and why is it required? > > At WEpayments, you will find two distinct KYC contexts: > > **KYC for account onboarding** > > When WEpayments is responsible for onboarding your company's account, we may request documents to complete the due-diligence process and activate your account. > > **KYC for transaction users** > > In some cases, WEpayments must collect or validate information about your users — such as payout beneficiaries or payin payers. Specific documentation may be required to process these transactions in compliance with regulatory and risk policies. > > For more details, please refer to the [full KYC documentation](/api-reference/kyc/list-kyc). > [accordion] What happens if there's a CPF Mismatch? > > If the CPF doesn't match the account holder, the transaction is rejected with error codes: > > * **RESTRICTION\_PAYER\_DIVERGENCE** (for deposits) > * **BENEFICIARY\_DIVERGENT** (for withdrawals) > > See [CPF Mismatch](/features/cpf-mismatch) for more details. > [accordion] How do I check my account balance? > > Use the [Get Balance](/api-reference/account/get-balance) endpoint to retrieve your current account balance. > [accordion] How do I get a list of supported banks? > > Use the [List Institutions](/api-reference/banks/list-institutions) endpoint to get all supported banks. > [accordion] What should I do if I receive a 401 Unauthorized error? > > This error means your API key is invalid or missing. Check that: > > * You're using the correct API key for the environment (Sandbox/Production) > * The API key is included in the Authorization header as a Bearer token > * The API key hasn't been revoked or expired > > If you need to create or regenerate your API key, follow the instructions: [How to create an API key](https://support.wepayments.com.br/support/legal/api-authentication) > [accordion] How do I handle webhook retries? > > If your endpoint doesn't respond with a 200 status code, WEPayments will retry: > > * 1st retry: After 1 minute > * 2nd retry: After 5 minutes > * 3rd retry: After 30 minutes > * 4th retry: After 2 hours > * 5th retry: After 6 hours > > After 5 failed attempts, you'll receive an email notification. > [accordion] How do I go to production? > > To move your integration to production, follow the steps below: > > 1. Complete all testing in the Sandbox environment. > 2. Notify your onboarding contact that the homologation phase has been completed. > 3. Our team will review and confirm your production access approval. > 4. Once approved, collect your production API keys and provide your production IP addresses for whitelisting. > 5. Configure your webhooks using the production endpoints. > > After completing these steps, your environment will be ready to go live. > > For more details, see the [Going to Production](/going-to-production) guide. > [accordion] Where can I check the API status? > > Visit our [Status Page](https://wepayments.instatus.com/) to check the current status of our APIs and services. > [accordion] How do I contact support? > > **24/7 Support Team**: Our Support, Performance & CX team is available for operational and technical assistance. > > **Help Center**: Access articles on panel usage, transactions, payments, withdrawals, reports, and more. > > * **Chat**: Click the chat icon in the bottom-right corner of any Help Center page. [Access Help Center](https://support.wepayments.com.br/) > * **WhatsApp**: +55 41 9266-7191 > * **E-mail**: [cs@wepayments.com.br](mailto:cs@wepayments.com.br) ## Still have questions? If you couldn't find the answer you're looking for, please contact our support team: > [card] [Integration Team](mailto:integration@wepayments.com.br) > > For API and integration questions > [card] [General Support](mailto:support@wepayments.com) > > For general inquiries and assistance > [card] [Status Page](https://wepayments.instatus.com/) > > Check API status and uptime > [card] [Dashboard](https://app.wepayout.co/#/dashboard) > > Access your account dashboard # CPF Mismatch Source: https://docs.wepayout.co/features/cpf-mismatch Prevent fraud by ensuring CPF verification on deposits and withdrawals ## What is CPF Mismatch? **CPF Mismatch** is a feature that rejects transactions when the CPF of the user's making a deposit or receiving a prize does not match the CPF of the account holder. This measure ensures that only the authorized holder can make payments and withdrawals, preventing fraud and ensuring compliance with local regulations, such as Ordinance 1330 of 26/10/2023, which prohibits third-party deposits in bettors' accounts. ## How does it work? ### Payin (Deposits) When receiving a payment via a WE QR Code, the system checks whether the payer's CPF matches the CPF associated with the original request. If the information does not match, the transaction is rejected and the merchant receives a notification with the error code **RESTRICTION\_PAYER\_DIVERGENCE**. > [!NOTE] > > **Optional Feature**: This functionality is configurable. It is required for specific segments—such as betting—but if you want it enabled for your business, please let us know. ### Payout (Withdrawals) This validation also applies to the withdrawal (payout) flow. Before completing the payment to the beneficiary, the system verifies whether the CPF matches the registered account holder. If it does not, the transaction is canceled with the reason **BENEFICIARY\_DIVERGENT**. > [!NOTE] > > **Default Feature**: This is a default functionality and does not require any configuration. These controls ensure that only the legitimate account owner can perform financial transactions, increasing security for both the operator and the end user. ## Key Benefits > [card] Fraud Prevention > > Prevents unauthorized transactions by verifying CPF ownership > [card] Regulatory Compliance > > Complies with Ordinance 1330 of 26/10/2023 > [card] Real-time Validation > > Instant verification before transaction completion > [card] Customer Protection > > Protects both operators and end customers ## Transaction Flow ### Deposits (QR Code Payments) **1. QR Code Generation** WEPayments generates a QR code for the payment request **2. User Scans QR Code** User scans the QR code to make the payment **3. CPF Verification** System checks if payer's CPF matches the registered account holder's CPF **4. Transaction Result** If CPF matches: Payment is processed If CPF doesn't match: Transaction is rejected with error code ### Withdrawals (Payouts) **1. Withdrawal Request** User requests a withdrawal to their registered account **2. CPF Verification** System verifies if the beneficiary's CPF matches the registered holder **3. Transaction Result** If CPF matches: Payment is completed If CPF doesn't match: Transaction is canceled ## Error Codes | Error Code | Type | Description | | - | - | - | | **RESTRICTION\_PAYER\_DIVERGENCE** | Deposit | The payer's CPF does not match the account holder's CPF | | **BENEFICIARY\_DIVERGENT** | Withdrawal | The beneficiary's CPF does not match the registered holder's CPF | ## Use Cases > [accordion] Betting Platforms > > Ensures compliance with regulations that prohibit third-party deposits in bettors' accounts, as mandated by Ordinance 1330. > [accordion] Financial Services > > Prevents money laundering and fraud by ensuring only the account owner can perform transactions. > [accordion] E-commerce > > Protects merchants and customers by verifying the identity of the person making payments or receiving refunds. > [accordion] Marketplaces > > Ensures sellers receive payments only to their registered accounts, preventing fraud. ## Best Practices > [!NOTE] > > **User Registration**: Ensure users register their correct CPF during account creation to avoid transaction rejections. > [!WARNING] > > **Third-Party Payments**: Transactions from third-party accounts will be automatically rejected to comply with regulations. > [!TIP] > > **Error Handling**: Implement proper error handling in your application to inform users when a CPF mismatch occurs. ## Regulatory Compliance This feature helps you comply with: * **Ordinance 1330 of 26/10/2023**: Prohibits third-party deposits in bettors' accounts * **Anti-Money Laundering (AML)** regulations * **Know Your Customer (KYC)** requirements ## Related Resources > [card] [KYC Verification](/api-reference/kyc/list-kyc) > > Know Your Customer verification > [card] [Create Charge](/api-reference/cash-in/payin/create-charge) > > Create payment charges > [card] [Create Payment](/api-reference/cash-out/payout/create-payment) > > Create payout payments # Going to Production Source: https://docs.wepayout.co/going-to-production Checklist and best practices for launching your integration This guide will help you prepare your WEpayments integration for production. Follow this checklist to ensure a smooth launch. ## Pre-Launch Checklist ### 1. Testing & Validation > [accordion] ✓ Complete Integration Testing > > * [ ] All API endpoints tested in Dev Mode > * [ ] Success scenarios verified > * [ ] Error handling tested > * [ ] Edge cases covered > * [ ] Payment flows work end-to-end > [accordion] ✓ Webhook Implementation > > * [ ] Webhooks registered and tested > * [ ] Webhook `secret` registered and HMAC-SHA256 signature verification implemented > * [ ] Retry logic in place > * [ ] Idempotency handling configured > * [ ] All event types handled > [accordion] ✓ Security Review > > * [ ] API keys stored securely > * [ ] HTTPS enabled on all endpoints > * [ ] Input validation implemented > * [ ] Rate limiting configured > * [ ] Security headers set > [accordion] ✓ Error Handling > > * [ ] All error codes handled > * [ ] User-friendly error messages > * [ ] Logging implemented > * [ ] Monitoring set up > * [ ] Alerting configured ### 2. Account Configuration **1. Verify Business Information** Ensure all business details are accurate in your dashboard **2. Configure Transfer Accounts** Set up another bank account with the same ownership for transfer funds **3. Enable Two-Factor Authentication (2FA)** After receiving access to the production panel, you must activate 2FA for enhanced security. [Learn how to enable 2FA](https://support.wepayments.com.br/support/legal/security-login#two-factor-authentication-2fa) ### 3. API Keys & Credentials > [!WARNING] > > **Critical**: Never expose your production API keys in client-side code or public repositories. ```javascript theme={null} // ✅ Good - Using environment variables const apiKey = process.env.WEPAYMENTS_API_KEY; // ❌ Bad - Hardcoded key const apiKey = 'live_sk_1234567890abcdef'; ``` **Production API Keys Checklist:** * [ ] Generate production API keys * [ ] Store keys in secure environment variables * [ ] Remove all test keys from production code * [ ] Implement key rotation policy * [ ] Restrict API key permissions * [ ] Configure allowed IPs for API requests > [!NOTE] > > **Important**: After accessing the production panel, configure the allowed IPs that can make API requests. This adds an extra layer of security to your integration. [Learn how to configure allowed IPs](https://support.wepayments.com.br/support/legal/api-authentication#step-4-configure-allowed-ip-addresses) ## Launch Day ### Final Steps **1. Switch to Production Keys** Update all API keys to production values **2. Enable Production Webhooks** Verify webhooks are pointing to production URLs **3. Test First Transaction** Process a small real transaction to verify everything works **4. Monitor Closely** Watch logs and monitoring tools for the first few hours **5. Be Ready to Respond** Have your team available to address any issues ### Post-Launch Monitoring For the first 24-48 hours: * Monitor transaction success rates * Watch for error spikes * Check webhook delivery rates * Review customer feedback * Verify settlement timing ## Common Issues & Solutions > [accordion] High Error Rates > > **Symptoms**: Many failed transactions > > **Solutions**: > > * Check API key is correct > * Verify endpoint URLs > * Review error logs > * Check rate limits > [accordion] Webhook Failures > > **Symptoms**: Webhooks not being received > > **Solutions**: > > * Verify webhook URL is accessible > * Check HTTPS certificate > * Review webhook logs in dashboard > * Test signature verification > [accordion] Performance Issues > > **Symptoms**: Slow response times > > **Solutions**: > > * Implement caching > * Optimize database queries > * Use async processing > * Scale infrastructure ## Support During Launch > [card] Priority Support > > Contact [support@wepayments.com](mailto:support@wepayments.com) for launch assistance > [card] Documentation > > Reference our complete API documentation ## Congratulations! 🎉 You're now ready to go live with WEpayments. Remember: * Start small and scale gradually * Monitor everything closely * Respond quickly to issues * Keep improving the experience Need help? We're here for you at [support@wepayments.com](mailto:support@wepayments.com) # About Markup Source: https://docs.wepayout.co/markup/about-markup Understanding markup solution Allows merchants to generate additional revenue by applying a flexible, custom markup to their submerchants' transactions, with WePayments' fees charged separately for different payment methods and transaction types. *** ## Configuration Levels (Scopes) Merchants can configure markup at three different levels: ### Global (Merchant Level) The merchant defines a markup that is applied to **all transactions from all submerchants**. This is the default when no other level applies. ### By Submerchant The merchant can define a specific markup for **each individual submerchant**, per product (`payin` or `payout`) and payment method. See [Submerchant Markup endpoints](/api-reference/markup/submerchant/list-submerchant-markups). ### Inline in Request (By Charge or Payment) When creating a charge or payment, the merchant can send a specific `markup` object. ## Priority Rule For each transaction, the markup is chosen in this order: 1. **Inline markup** sent in the request. 2. **Submerchant markup** configured for the submerchant. 3. **Global markup** configured for the merchant. The choice is made **per payment method**. For example, if a submerchant has its own markup for Pix but not for Boleto, a Pix charge uses the submerchant markup and a Boleto charge uses the global markup. > [!NOTE] > > **If there is no inline or submerchant markup → the global markup is applied when the merchant has the markup feature enabled.** Changes to submerchant or global markup, including batch changes, apply to the next transactions created. ## Markup Origin The `markup` object returned for a charge or payment includes an `origin` field that shows which level was applied: | `origin` | Meaning | | - | - | | `inline` | The markup was sent in the request | | `sub_merchant` | The submerchant's own markup was applied | | `global` | The merchant's global markup was applied | | `null` | Transaction created before this field was available | ## Products and Payment Methods | Product | Payment methods | | - | - | | `payin` | `pix`, `billet`, `credit_card` | | `payout` | `pix`, `ted` | > [!NOTE] > > When creating a payout, markup is currently applied to **PIX** payments only. *** ## Markup Types ### Fixed The same fixed markup value is applied to all charges/payments, regardless of the transaction amount. ### Percentage The markup value is calculated as a percentage of the charge/payment amount. This type includes delimiter fields to define a valid range for the final markup amount: * `min_charge_value`: The minimum markup amount to be charged. * `max_charge_value`: The maximum markup amount to be charged. > [!NOTE] > > For submerchant markup, both `min_charge_value` and `max_charge_value` are required when the type is percentage. #### Percentage Calculation Logic 1. The system calculates the raw percentage value (transaction\_amount \* percentage). 2. If the calculated value is **less** than min\_charge\_value, the min\_charge\_value is applied. 3. Else if the calculated value is **greater** than max\_charge\_value, the max\_charge\_value is applied. 4. Otherwise, the exact calculated value is applied. Examples (BRL): | Transaction | Markup % | Min Value | Max Value | Calculation | Applied | Reason | | - | - | - | - | - | - | - | | R\$ 10.00 | 0.3% | R\$ 0.05 | R\$ 0.15 | R\$ 0.03 | R\$ 0.05 | Uses min\_charge\_value (0.03 \< 0.05) | | R\$ 10.00 | 1.7% | R\$ 0.05 | R\$ 0.15 | R\$ 0.17 | R\$ 0.15 | Uses max\_charge\_value (0.17 > 0.15) | | R\$ 10.00 | 1.2% | R\$ 0.05 | R\$ 0.15 | R\$ 0.12 | R\$ 0.12 | Uses calculated value (0.05 \< 0.12 \< 0.15) | ## Related Resources > [card] [Creating Markup via API](/markup/creating-markup-api) > > Guide for configuring markup using the API > [card] [Create Merchant Markup](/api-reference/markup/account/create-merchant-markup) > > Create new markup configurations > [card] [List Merchant Markups](/api-reference/markup/account/list-merchant-markups) > > View all markup configurations > [card] [Create Payin with Inline Markup](/api-reference/markup/payin/create-payin-with-inline-markup) > > Use inline markup when creating payin charges > [card] [Submerchant Markups](/api-reference/markup/submerchant/list-submerchant-markups) > > Configure markup for each submerchant # Creating Markup via API Source: https://docs.wepayout.co/markup/creating-markup-api How to configure markup for merchants using the API. # Creating Global Markup To create and manage global markup configurations for your merchants, use the following endpoints: * [Create Merchant Markup](/api-reference/markup/account/create-merchant-markup) * [Update Merchant Markup](/api-reference/markup/account/update-merchant-markup) * [List Merchant Markups](/api-reference/markup/account/list-merchant-markups) # Creating Submerchant Markup To give a submerchant its own markup, which takes priority over the global markup, use the following endpoints: * [List Submerchant Markups](/api-reference/markup/submerchant/list-submerchant-markups) * [Get Submerchant Markup](/api-reference/markup/submerchant/get-submerchant-markup) * [Configure Submerchant Markup](/api-reference/markup/submerchant/upsert-submerchant-markup) * [Remove Submerchant Markup](/api-reference/markup/submerchant/delete-submerchant-markup) * [Batch Apply Submerchant Markup](/api-reference/markup/submerchant/batch-apply-submerchant-markup) A typical flow: 1. **List** the merchant's submerchants to find the ones to configure. Use `search` to filter by name, ID or document. 2. **Configure** the markup of one submerchant, or **batch apply** the same markup to many submerchants. 3. **Remove** the submerchant markup when the submerchant should go back to the global markup. > [!WARNING] > > Configuring a submerchant replaces its whole markup configuration. Send every product and payment method you want to keep. ## Related Resources > [card] [About Markup](/markup/about-markup) > > Learn about markup types and configuration levels > [card] [Create Merchant Markup](/api-reference/markup/account/create-merchant-markup) > > Create new markup configurations > [card] [Configure Submerchant Markup](/api-reference/markup/submerchant/upsert-submerchant-markup) > > Set the markup of a submerchant > [card] [Create Payin with Global Markup](/api-reference/markup/payin/create-payin-with-global-markup) > > Use global markup when creating payin charges > [card] [Create Payout with Global Markup](/api-reference/markup/payout/create-payout-with-global-markup) > > Use global markup when creating payout payments # Model Context Protocol (MCP) Source: https://docs.wepayout.co/model-context-protocol Connect our documentation to your AI tools via MCP The Model Context Protocol (MCP) allows you to connect WePayout's documentation directly to your AI tools (like Claude, Cursor, or VS Code). This enables the AI to have real-time access to our latest API reference, guides, and concepts. ## MCP Server URL Use the following URL to connect to our hosted MCP server: ``` https://docs.wepayout.co/mcp ``` ## How to use ### Claude 1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in your Claude settings. 2. Select **Add custom connector**. 3. Enter a name (e.g., `WePayout`) and the MCP URL: `https://docs.wepayout.co/mcp`. 4. Click **Add**. 5. When chatting with Claude, click the plus icon (attachments) and select the **WePayout** connector. ### Cursor 1. Open the command palette (`Cmd/Ctrl + Shift + P`). 2. Search for "Open MCP settings". 3. Select **Add custom MCP**. This opens your `mcp.json` file. 4. Add the WePayout server configuration: ```json theme={null} { "mcpServers": { "wepayout": { "url": "https://docs.wepayout.co/mcp" } } } ``` ### VS Code (with Copilot) 1. Create or open `.vscode/mcp.json` in your project. 2. Add the following configuration: ```json theme={null} { "servers": { "wepayout": { "type": "http", "url": "https://docs.wepayout.co/mcp" } } } ``` ### Claude Code You can also add the MCP server via the CLI: ```bash theme={null} claude mcp add --transport http wepayout https://docs.wepayout.co/mcp ``` For more details on MCP, visit the [official Mintlify documentation](https://www.mintlify.com/docs/ai/model-context-protocol).