Create Payout

Create a payout request to selected beneficiary account.

This endpoint initiates a fund transfer from your virtual pool to a recipient’s bank account using a registered payout provider. Once created, the payout will enter a pending or processing state depending on bank handling times.

Use this endpoint after retrieving available payout providers via Payout Provider.

Endpoint

POST

https://api.payright.my/api/v1/merchant/payout

Usage Examples

curl -X POST "https://api.payright.my/api/v1/merchant/payout" \
  -H "auth-token: eyJhbGciO...XZI3CLi_a0BeUOJMPUK00" \
  -H "Content-Type: application/json" \
  -d '{
    "virtual_pool_reference": "VA-ABC-1234-PAYOUT",
    "payout_service_id": 14,
    "amount": 10.20,
    "client_redirect_url": "https://www.example.com/redirect",
    "client_callback_url": "https://www.example.com/callback",
    "third_party_account_no": "12345678901",
    "recipient_reference": "john_doe",
    "payment_description": "June Payout",
    "external_invoice_ref": "INV-0123"
  }'

import http.client
import json
import urllib.parse

# Parse the URL
url = "https://api.payright.my/api/v1/merchant/payout"
parsed_url = urllib.parse.urlparse(url)

# Create HTTPS connection
conn = http.client.HTTPSConnection(parsed_url.hostname)

# Prepare headers
headers = {
    "auth-token": "eyJhbGciO...XZI3CLi_a0BeUOJMPUK00",
    "Content-Type": "application/json"
}

# Define the payload to send in the POST body
payload = {
    "virtual_pool_reference": "VA-ABC-1234-PAYOUT",
    "payout_service_id": 14,
    "amount": 10.20,
    "client_redirect_url": "https://www.example.com/redirect",
    "client_callback_url": "https://www.example.com/callback",
    "third_party_account_no": "12345678901",
    "recipient_reference": "john_doe",
    "payment_description": "June Payout",
    "external_invoice_ref": "INV-00123"
}

# Convert the Python dictionary to a JSON string
json_payload = json.dumps(payload)

# Send POST request
conn.request("POST", parsed_url.path, body=json_payload, headers=headers)

# Read response
response = conn.getresponse()
print("Status:", response.status)
print("Response:", response.read().decode())

# Close connection
conn.close()

require 'net/http'
require 'uri'
require 'json'

# Parse the URL
url = URI.parse("https://api.payright.my/api/v1/merchant/payout")

# Create HTTP request
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url.path, {
  "auth-token" => "eyJhbGciO...XZI3CLi_a0BeUOJMPUK00",
  "Content-Type" => "application/json"
})

# Define the JSON payload to send in the POST body
request.body = {
  virtual_pool_reference: "VA-ABC-1234-PAYOUT",
  payout_service_id: 14,
  amount: 10.20,
  client_redirect_url: "https://www.example.com/redirect",
  client_callback_url: "https://www.example.com/callback",
  third_party_account_no: "12345678901",
  recipient_reference: "john_doe",
  payment_description: "June Payout",
  external_invoice_ref: "INV-00123"
}.to_json

# Execute request
response = http.request(request)

# Output result
puts "Status: #{response.code}"
puts "Response body: #{response.body}"

Authentication

string header required

To authenticate requests, include an Authorization header with the value

Key

Value

auth-token

You can retrieve your token by visiting your Payright dashboard and clicking Accounts > API Keys > View API Keys (magnify icon) > Auth Token

Request

Body

application/json

Example Request Body

{
  "virtual_pool_reference": "VA-AE81DE-120345369538-PAYOUT",
  "payout_service_id": 14,
  "amount": 24.50,
  "client_redirect_url": "https://www.payright.my/ms",
  "client_callback_url": "https://webhook.site/36d8f28e-972c-4777-b574-bbd9d96e4949",
  "third_party_account_no": "12345678901",
  "recipient_reference": "test3",
  "payment_description": "test payment description3",
  "external_invoice_ref": "Payright03"
}

Request Attributes

virtual_pool_reference ^_string^_required

Reference to the sender’s virtual pool used for the payout.

payout_service_id ^_integer^_required

ID of the payout service (retrieved from Payout Provider).

amount ^{_{decimal(10,2)}}^_required

Total amount to be paid in MYR.

client_redirect_url ^_string ^_required

URL to redirect the user to after payment action is completed.

client_callback_url ^_string ^_required

Webhook callback URL for receiving async status updates.

third_party_account_no ^_string^_required

Recipient’s bank account number.

recipient_reference ^_string^_required

Reference or name of the recipient.

payment_description ^_string^_required

Description of the payment purpose.

external_invoice_ref ^_string^_required

External reference number you assign the client for tracking the payout.

Response

application/json

{
    "status": "ok",
    "code": 2000,
    "data": {
        "status": "SUCCESS",
        "invoice_no": "po-6DC1:125037-pyt"
    },
    "uuid": "408ed601-0cf9-4835-9bef-f734410741dc",
    "message": null,
    "error": null
}

Response Attributes

status ^_string

Response status indicator (e.g., "ok" or "fail").

code ^_number

HTTP-like status code representing result (200 = success).

data ^{_{object | null}}

Field

Type

Description

status

string

Payout transaction result, e.g., SUCCESS, FAILED, or PENDING.

invoice_no

string

Unique internal invoice number for this payout transaction.

uuid ^{_{string | null}}

Unique request identifier useful for debugging or tracing logs.

message ^{_{string | null}}

Optional human-readable message (e.g., for error or info).

error ^{_{string | null}}

Optional error description if something went wrong.

Last updated 3 months ago