API Payout

Local Payout

API Payout

API Payout is designed for merchants with an existing business system: the system initiates payouts automatically based on orders, settlement, or operational workflows, without manual action in the Merchant Dashboard. PayCools handles payout acceptance, channel processing, and result delivery, helping merchants embed payout capabilities into their own business processes.

1

Mode Overview

In API Payout mode, payouts are initiated automatically by the business system, making it suitable for embedding payout capabilities into existing business processes. Compared with Merchant Dashboard payouts, the main differences are:

• Automatic initiation: The business system calls the API to create payouts based on order or settlement workflows, suitable for high-frequency, high-volume scenarios.
• Channel selection by business rules: The recipient channel can be specified when initiating a payout, covering local banks and e-wallets in supported countries.
• Asynchronous results: After PayCools accepts a payout, it enters processing. The final result is obtained through an asynchronous notification or query. The acceptance result is not proof of payout success.
• Batch ordering: In addition to single payouts, a batch payout API is available for submitting one batch at a time.

2

Use Cases

• High-frequency, high-volume payouts: User withdrawals, commission payouts, campaign rewards, and other scenarios with many transactions that require automated disbursement per transaction.
• Business system integration: Orders, settlement, or accounting systems trigger payouts automatically based on business status, without manual intervention.
• Batch settlement: Supplier settlement, batch payroll, and other scenarios that pay multiple recipients at once can use the batch payout API.
• Automated reconciliation: Write payout results back to the business system through asynchronous callbacks and the query API for reconciliation.

3

Interaction Flow

After the business system creates a payout, PayCools pushes it to the channel and returns the result. Initiating the payout, receiving notifications, and updating order status are all handled by the merchant system.

4

Integration Steps

1. Create a Payout (Payout Order)

The business system calls the payout order API to initiate a payout. After acceptance, PayCools returns PENDING and then asynchronously pushes the payout to the channel. The order API does not return success directly; the final result is determined by the asynchronous notification or query result. View API documentation

note

Before placing an order, we recommend calling Account Verification to validate the recipient account. Confirm that the account is valid (accountStatus=VALID) and the name matches (accountNameMatchResult=MATCH) before initiating the payout. This reduces failures caused by incorrect account numbers or names. Account Verification must be enabled separately.

Endpoint: POST /open-api/disbursement/transfer

Create Payout Request Example

curl --location --request POST 'https://globalapi-dev.paycools.com:8902/open-api/disbursement/transfer' \
--header 'Content-Type: application/json' \
--data-raw '{
    "appId": "3490xxxxxxa8af",
    "sign": "<your_sign>",
    "param": "{\"countryCode\":\"PH\",\"currency\":\"PHP\",\"mchOrderId\":\"10e0604985585335100\",\"idempotencyId\":\"10e0604985585335100\",\"amount\":100,\"accountNo\":\"09206634895\",\"accountName\":\"test\",\"payMethodCode\":\"EWALLET\",\"transferCode\":\"GCASH\",\"beneficiaryType\":\"INDIVIDUAL\",\"accountType\":\"MOBILE_NUMBER\",\"timestamp\":1720604986}"
}'

Create Payout Response Example

{
  "code": 10000,
  "message": "Success",
  "data": {
    "mchOrderId": "10e0604985585335100",
    "transactionId": "DU510974822121865216",
    "transactionStatus": "PENDING",
    "transactionTime": "2024-07-10T17:50:18+08:00"
  }
}

2. Receive Payout Result Notifications

When a payout status changes, PayCools sends an asynchronous notification to the payout callback URL configured in the Merchant Dashboard. Configure the callback URL under Developer Settings → Application Details → Webhook. Notifications may be resent until the merchant returns a successful response. For delivery, retry, and timeout rules, see General Callback Notification Rules.

What the merchant needs to do:

1. After receiving the notification, verify the sign with the platform public key to confirm that the notification came from PayCools.
2. Parse the transaction result in param and update the local order status based on eventName (disbursement.success / disbursement.failed) and transactionStatus.
3. If the payout failed, read failedCode / failedMessage to identify the cause.
4. Return HTTP 200 to acknowledge receipt.

note

For complete notification field descriptions and examples, see the Payout Result Callback Documentation.

3. Query Payout Status

If the asynchronous notification is not received in time, the callback endpoint is unavailable, or you need to reconcile or proactively confirm a payout result, call the query API to obtain the latest status of a payout.

What the merchant needs to do:

1. Call the query API with mchOrderId or transactionId (either one) and countryCode.
2. Update the order status based on the returned transactionStatus.
3. If the payout failed, obtain the cause from failedCode / failedMessage.

note

For complete request and response parameters, see the Query Payout Status API Documentation.

5

API Reference

The payout order API uses a unified appId / sign / param request structure, where param is a JSON string of business parameters (the signature is generated over the param content). Key parameters are listed below:

Parameter	Description
mchOrderId	Merchant order number, 10–32 characters, must be unique
idempotencyId	Idempotency key; keep it unchanged for the same request to prevent duplicate submission
countryCode / currency	Payout country and currency; the two must match
amount	Payout amount; the unit follows the API documentation (IDR and VND use the base unit; other currencies use cents)
accountNo / accountName	Recipient account and name. The payout is made to the account number; the name is recorded and passed through without validation
payMethodCode / accountType / transferCode	Payout method, account type, and specific recipient channel code

note

Payouts validate only the recipient account number. A payout can succeed as long as the account number is correct; the platform does not verify whether the recipient name is correct or real. An incorrect name usually does not affect the result. To confirm the account holder name in advance, use Account Verification.

Response

The order API returns the transaction ID and the immediate status of the payout. Key fields are:

Field	Description
mchOrderId	Merchant order number
transactionId	Unique PayCools transaction ID, used for reconciliation
transactionStatus	Fixed to PENDING in the order response; the final status (COMPLETED / FAILED) is obtained through an asynchronous notification or the query API
transactionTime	Transaction creation time

note

The transactionStatus in the order response is always PENDING. It only means the request has been accepted and cannot be used to determine payout success. The final result is based on the asynchronous notification or query result. Payouts initiated through the API cannot be revoked; verify the recipient information and amount before submitting.

6

Merchant Responsibilities

PayCools accepts payouts, pushes them to channels, and returns results. The following steps must be handled by your business system:

• Create payouts: Call the order API based on business status, pass the recipient information and payout amount for each transaction, and ensure that mchOrderId and idempotencyId are unique.
• (Optional) Verify before payout: Validate account validity and name matching before placing the order to significantly reduce payout failures.
• Receive and verify notifications: After a callback arrives, verify the signature with the platform public key and update the order based on eventName and transactionStatus.
• Status confirmation: Use the final status from the asynchronous notification or query API. Do not treat the PENDING response or the user-facing display as proof of success.
• Failure handling and retries: Determine the cause from failedCode / failedMessage; recoverable issues such as insufficient balance can be retried.
• Reconciliation: Reconcile by transactionId and handle duplicate notifications with idempotent updates.

7

Integration Preparation

Before integrating API Payout, ensure that:

1. Commercial discussions are complete and the merchant name and email address have been provided so that technical support can send the account information.
2. The public key has been configured in the Merchant Dashboard, and the AppID and platform public key have been obtained.
3. You understand the signature and verification mechanism, and requests include the sign.
4. The payout result callback URL (Notify URL) has been configured on the API Key page.
5. You have reviewed the environment information and confirmed the request URL.
6. The merchant account balance is sufficient to cover the payout amount + fee.