Step 8: Create Withdrawal Request (APM Payout)

Important Withdrawal Logic

• Once customer and APM account information is available, you may initiate a withdrawal.
• The system attempts to use available deposited balance first.
• Withdrawals are processed as APM payouts.

Endpoint

POST /api/v1/payment/withdrawal

Request Body

{
  "reference": "THDBSHSGDH19",
  "customerToken": "8cef59ce80749fb750a78d4e40b1ba8d",
  "amount": "50",
  "currency": "BRL",
  "solutionUniqueId": "eae69d12-3d30-490c-ba82-6eeed6b3a455",
  "merchantAccountId": "100012",
  "accountToken": "e617a17d-68b3-42a5-9174-9657528e3dc1",
  "webhookUrl": "https://webhook.site/96eadec6-740f-4e88-a196-1acec1a32b95"
}

Note: Use either customerToken or customerReferenceId.

---

Webhook Notification

Once the withdrawal is processed, the system will send status notifications to the provided webhookUrl.

Sample Withdrawal Webhook Response

{
  "status": "success",
  "type": "withdrawal",
  "reference": "THDBSHSGDH19",
  "amount": "50.00",
  "currency": "BRL",
  "created_at": "2026-01-21T12:21:15.000000Z",
  "responses": [
    {
      "solution_name": "PIX - Unlimit - New",
      "transaction_id": "22977037",
      "amount": "50.0000",
      "transaction_type": "payout",
      "remarks": null,
      "timestamps": "2026-01-21T12:21:16.000000Z",
      "status": "success"
    }
  ]
}

Webhook Field Description

Field	Description
status	Overall withdrawal status (success, failed, pending)
type	Transaction type (withdrawal)
reference	Merchant-defined unique withdrawal reference
amount	Total withdrawal amount
currency	Transaction currency
created_at	Withdrawal creation timestamp
responses	PSP-level transaction execution details
responses.solution_name	APM / PSP solution name
responses.transaction_id	PSP transaction identifier
responses.transaction_type	Transaction type (payout)
responses.status	PSP transaction status
responses.remarks	Failure or informational message from PSP (if any)

Webhook Handling Notes

• Webhook is sent after final PSP processing.
• Always validate the reference before updating internal records.
• Multiple response objects may be returned in retry or split-processing scenarios.
• Return HTTP 200 OK to acknowledge successful receipt.

---

Final Notes

• All requests require Basic Authentication.
• Use unique reference values for each transaction.
• Store tokens securely and never expose them on the client side.