Withdrawals

Endpoints to create and query withdrawals via PIX.

POST /v1/withdrawals

Creates a new withdrawal via API with idempotency support.

Headers

http

Authorization: Bearer {access_token}
Content-Type: application/json
Idempotency-Key: {unique_key}

IMPORTANT

The Idempotency-Key header is required to prevent withdrawal duplication. Use a UUID v4 or unique string.

Request Body

Field	Type	Required	Description
`amount`	number	✅ Yes	Withdrawal amount in reais (e.g. 10.00)
`pix_key`	string	⚠️ Conditional	Destination PIX key (required if not configured in system)
`pix_key_type`	string	⚠️ Conditional	PIX key type (`cpf`, `cnpj`, `phone`, `random`, `email`) (required if not configured in system)
`authorize`	boolean	✅ Yes	Whether to attempt auto-approval (true)

NOTE

The pix_key and pix_key_type fields are conditional: they are required only if the merchant does not have a PIX key configured in the system. If a key is already configured, these fields are optional and, if provided, will override the default key for this specific withdrawal.

Request Example

bash

curl -X POST https://api.misespay.com/v1/withdrawals \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "amount": 10.00,
    "pix_key": "12312312312",
    "pix_key_type": "cpf",
    "authorize": true
  }'

Response (201 Created)

json

{
  "success": true,
  "message": "Withdrawal requested successfully",
  "data": {
    "withdrawal_id": "881c686a-9e53-4809-a63c-c2730b924ea7",
    "amount": "R$ 10,00",
    "fee_amount": "R$ 0,20",
    "net_amount": "R$ 9,80",
    "status": "processing",
    "origin": "api",
    "pix_key": "12312312312",
    "pix_key_type": "cpf",
    "requires_merchant_approval": false,
    "requires_compliance_review": false,
    "e2e_id": null,
    "created_at": "2025-12-26T11:50:03-03:00"
  }
}

Response (200 OK - Idempotent)

If the same Idempotency-Key is sent again:

json

{
  "success": true,
  "message": "Withdrawal already processed previously",
  "data": {
    "withdrawal_id": "881c686a-9e53-4809-a63c-c2730b924ea7",
    "amount": "R$ 10,00",
    "fee_amount": "R$ 0,20",
    "net_amount": "R$ 9,80",
    "status": "processing",
    "origin": "api",
    "pix_key": "12312312312",
    "pix_key_type": "cpf",
    "requires_merchant_approval": false,
    "requires_compliance_review": false,
    "e2e_id": null,
    "created_at": "2025-12-26T11:50:03-03:00"
  },
  "idempotent": true
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the operation was successful
`message`	string	Descriptive message
`data.withdrawal_id`	string (UUID)	Unique withdrawal ID
`data.amount`	string	Withdrawal amount formatted
`data.fee_amount`	string	Fee charged formatted
`data.net_amount`	string	Net amount (after fee) formatted
`data.status`	string	Withdrawal status (see below)
`data.origin`	string	Withdrawal origin ("api", "portal")
`data.pix_key`	string	Destination PIX key
`data.pix_key_type`	string	PIX key type
`data.requires_merchant_approval`	boolean	If requires manual merchant approval
`data.requires_compliance_review`	boolean	If requires compliance review
`data.e2e_id`	string or null	PIX end-to-end ID (after processing)
`data.created_at`	string (ISO 8601)	Creation date/time
`idempotent`	boolean	Present only in idempotent responses

Withdrawal Status

Status	Description
`pending`	Awaiting approval
`processing`	In processing
`paid`	Withdrawal completed successfully
`failed`	Processing failed

Possible Errors

Test scenarios (payloads)

Use the payloads below to simulate common integration errors.

Endpoint	Scenario	Expected status
`POST /v1/withdrawals`	Missing Idempotency-Key	`400`
`POST /v1/withdrawals`	Invalid Idempotency-Key	`400`
`POST /v1/withdrawals`	PIX key not configured	`400`
`POST /v1/withdrawals`	Missing `amount`	`422`
`POST /v1/withdrawals`	Missing `authorize`	`422`
`POST /v1/withdrawals`	Invalid `amount` (0 or negative)	`422`
`POST /v1/withdrawals`	Invalid `pix_key_type`	`422`
`POST /v1/withdrawals`	`pix_key` provided without `pix_key_type`	`422`
`POST /v1/withdrawals`	`pix_key_type` provided without `pix_key`	`422`
`POST /v1/withdrawals`	Invalid CPF	`422`
`POST /v1/withdrawals`	Insufficient balance	`422`
`GET /v1/withdrawals/:id`	Withdrawal not found	`404`

POST /v1/withdrawals - 400 Missing Idempotency-Key

json

Headers:
  Authorization: Bearer {your_jwt_token}
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "authorize": true
}

Expected response:

json

{
  "success": false,
  "message": "Idempotency-Key header is required",
  "errors": {
    "idempotency_key": ["Idempotency-Key header is required"]
  }
}

POST /v1/withdrawals - 400 Invalid Idempotency-Key

json

Headers:
  Authorization: Bearer {your_jwt_token}
  Idempotency-Key: invalid@key#with$special%chars
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "authorize": true
}

Expected response:

json

{
  "success": false,
  "message": "Invalid Idempotency-Key. Use only letters, numbers, hyphens and underscores (maximum 255 characters)",
  "errors": {
    "idempotency_key": ["Invalid Idempotency-Key..."]
  }
}

POST /v1/withdrawals - 400 PIX Key Not Configured

json

Headers:
  Authorization: Bearer {your_jwt_token}
  Idempotency-Key: test-no-pix-key
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "authorize": true
}

Expected response:

json

{
  "success": false,
  "message": "PIX key not configured. Configure your PIX key or provide a custom PIX key in the request.",
  "errors": {
    "pix_key": ["PIX key not configured..."]
  }
}

POST /v1/withdrawals - 422 Missing amount

json

Headers:
  Authorization: Bearer {your_jwt_token}
  Idempotency-Key: test-no-amount
  Content-Type: application/json

Body:
{
  "authorize": true,
  "pix_key": "12345678901",
  "pix_key_type": "cpf"
}

Expected response:

json

{
  "success": false,
  "message": "Invalid data",
  "errors": {
    "amount": ["Withdrawal amount is required"]
  }
}

POST /v1/withdrawals - 422 Missing authorize

json

Headers:
  Authorization: Bearer {your_jwt_token}
  Idempotency-Key: test-no-authorize
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "pix_key": "12345678901",
  "pix_key_type": "cpf"
}

Expected response:

json

{
  "success": false,
  "message": "Invalid data",
  "errors": {
    "authorize": ["authorize is required"]
  }
}

POST /v1/withdrawals - 422 amount less than or equal to zero

json

Headers:
  Authorization: Bearer {your_jwt_token}
  Idempotency-Key: test-negative-amount
  Content-Type: application/json

Body:
{
  "amount": 0.00,
  "authorize": true,
  "pix_key": "12345678901",
  "pix_key_type": "cpf"
}

Expected response:

json

{
  "success": false,
  "message": "Invalid data",
  "errors": {
    "amount": ["Withdrawal amount must be greater than zero"]
  }
}

POST /v1/withdrawals - 422 Invalid pix_key_type

json

Headers:
  Authorization: Bearer {your_jwt_token}
  Idempotency-Key: test-invalid-pix-type
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "authorize": true,
  "pix_key": "12345678901",
  "pix_key_type": "invalid_type"
}

Expected response:

json

{
  "success": false,
  "message": "Invalid data",
  "errors": {
    "pix_key_type": ["PIX key type must be: cpf, cnpj, email, phone or random"]
  }
}

POST /v1/withdrawals - 422 pix_key provided without pix_key_type

json

Headers:
  Authorization: Bearer {your_jwt_token}
  Idempotency-Key: test-pix-no-type
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "authorize": true,
  "pix_key": "12345678901"
}

Expected response:

json

{
  "success": false,
  "message": "Invalid data",
  "errors": {
    "pix_key_type": ["pix_key_type is required when pix_key is provided"]
  }
}

POST /v1/withdrawals - 422 pix_key_type provided without pix_key

json

Headers:
  Authorization: Bearer {your_jwt_token}
  Idempotency-Key: test-type-no-pix
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "authorize": true,
  "pix_key_type": "cpf"
}

Expected response:

json

{
  "success": false,
  "message": "Invalid data",
  "errors": {
    "pix_key": ["pix_key is required when pix_key_type is provided"]
  }
}

POST /v1/withdrawals - 422 Invalid CPF

json

Headers:
  Authorization: Bearer {your_jwt_token}
  Idempotency-Key: test-invalid-cpf
  Content-Type: application/json

Body:
{
  "amount": 10.00,
  "authorize": true,
  "pix_key": "11111111111",
  "pix_key_type": "cpf"
}

Expected response:

json

{
  "success": false,
  "message": "Invalid data",
  "errors": {
    "pix_key": ["Invalid CPF"]
  }
}

POST /v1/withdrawals - 422 Insufficient Balance

json

Headers:
  Authorization: Bearer {your_jwt_token}
  Idempotency-Key: test-insufficient-balance
  Content-Type: application/json

Body:
{
  "amount": 999999.00,
  "authorize": true,
  "pix_key": "12345678901",
  "pix_key_type": "cpf"
}

Expected response:

json

{
  "success": false,
  "message": "Insufficient balance. Available: R$ X,XX | Required: R$ Y,YY",
  "errors": {
    "balance": ["Insufficient balance. Available: R$ X,XX | Required: R$ Y,YY"]
  }
}

GET /v1/withdrawals/:id - 404 Withdrawal Not Found

json

GET /v1/withdrawals/00000000-0000-0000-0000-000000000000

Headers:
  Authorization: Bearer {your_jwt_token}

Expected response:

json

{
  "success": false,
  "message": "Withdrawal not found",
  "errors": {
    "withdrawal": ["Withdrawal not found"]
  }
}

GET /v1/withdrawals/:id

Retrieves details of a specific withdrawal by ID.

Headers

http

Authorization: Bearer {access_token}

Path Parameters

Parameter	Type	Description
`id`	string (UUID)	Withdrawal ID

Request Example

bash

curl -X GET https://api.misespay.com/v1/withdrawals/881c686a-9e53-4809-a63c-c2730b924ea7 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Response (200 OK)

json

{
  "success": true,
  "data": {
    "withdrawal_id": "881c686a-9e53-4809-a63c-c2730b924ea7",
    "amount": "R$ 10,00",
    "fee_amount": "R$ 0,20",
    "net_amount": "R$ 9,80",
    "status": "paid",
    "origin": "api",
    "pix_key": "11999887766",
    "pix_key_type": "phone",
    "e2e_id": "E12345678202512261150abc123def456",
    "requires_merchant_approval": false,
    "requires_compliance_review": false,
    "bank_processing_status": "completed",
    "auto_approved": true,
    "compliance_status": "not_required",
    "processed_at": "2025-12-26T11:50:10-03:00",
    "created_at": "2025-12-26T11:50:03-03:00"
  }
}

Response Fields

Field	Type	Description
`withdrawal_id`	string (UUID)	Unique withdrawal ID
`amount`	string	Withdrawal amount formatted (e.g. "R$ 10,00")
`fee_amount`	string	Fee charged formatted (e.g. "R$ 0,20")
`net_amount`	string	Net amount formatted (e.g. "R$ 9,80")
`status`	string	Withdrawal status (see table above)
`origin`	string	Withdrawal origin ("api", "portal")
`pix_key`	string	Destination PIX key
`pix_key_type`	string	PIX key type
`e2e_id`	string or null	PIX end-to-end ID
`requires_merchant_approval`	boolean	If requires manual approval
`requires_compliance_review`	boolean	If requires compliance review
`bank_processing_status`	string	Bank processing status (see table below)
`auto_approved`	boolean	If was auto-approved
`compliance_status`	string	Compliance status (see table below)
`processed_at`	string (ISO 8601) or null	Processing date/time
`created_at`	string (ISO 8601)	Creation date/time

Bank Processing Status

Status	Description
`pending`	Awaiting bank processing
`processing`	Processing at bank
`completed`	Bank processing completed
`failed`	Bank processing failed

Compliance Status

Status	Description
`not_required`	Compliance review not required
`pending`	Awaiting compliance review
`under_review`	Under compliance review
`approved`	Approved by compliance
`rejected`	Rejected by compliance

Possible Errors

404 Not Found

json

{
  "success": false,
  "message": "Withdrawal not found"
}

401 Unauthorized

json

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

Withdrawal Status Flow

The withdrawal status follows the flow below, depending on the authorize parameter:

When `authorize: true` (auto-approval attempt)

Success: returns processing → can go to paid or failed
Failure: returns failed (final status)

When `authorize: false` (manual approval)

Creation: returns pending
After approval: goes to processing or failed
Processing: processing → can go to paid or failed

Final Statuses

Only two statuses are final (won't change anymore):

paid - Withdrawal completed successfully
failed - Withdrawal failed (may have failed at any stage)

Transition Diagram

authorize: true  → processing → paid ✓
                              → failed ✗

authorize: false → pending → processing → paid ✓
                          → failed ✗     → failed ✗

Withdrawal Flow

Check balance with /v1/balance
Generate Idempotency-Key unique (UUID v4)
Create withdrawal with /v1/withdrawals
Query status with /v1/withdrawals/:id when needed

Idempotency

TIP

Always use a unique UUID v4 for each withdrawal attempt. If there's a network failure, you can resend the same request with the same Idempotency-Key without risk of duplication.

See more details in Idempotency.

Next Steps

Balance - Query available balance
Idempotency - Understand how idempotency works

Withdrawals ​

POST /v1/withdrawals ​

Headers ​

Request Body ​

Request Example ​

Response (201 Created) ​

Response (200 OK - Idempotent) ​

Response Fields ​

Withdrawal Status ​

Possible Errors ​

Test scenarios (payloads) ​

GET /v1/withdrawals/:id ​

Headers ​

Path Parameters ​

Request Example ​

Response (200 OK) ​

Response Fields ​

Bank Processing Status ​

Compliance Status ​

Possible Errors ​

404 Not Found ​

401 Unauthorized ​

Withdrawal Status Flow ​

When authorize: true (auto-approval attempt) ​

When authorize: false (manual approval) ​

Final Statuses ​

Transition Diagram ​

Withdrawal Flow ​

Idempotency ​

Next Steps ​

Withdrawals

POST /v1/withdrawals

Headers

Request Body

Request Example

Response (201 Created)

Response (200 OK - Idempotent)

Response Fields

Withdrawal Status

Possible Errors

Test scenarios (payloads)

GET /v1/withdrawals/:id

Headers

Path Parameters

Request Example

Response (200 OK)

Response Fields

Bank Processing Status

Compliance Status

Possible Errors

404 Not Found

401 Unauthorized

Withdrawal Status Flow

When `authorize: true` (auto-approval attempt)

When `authorize: false` (manual approval)

Final Statuses

Transition Diagram

Withdrawal Flow

Idempotency

Next Steps