> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.sqril.io/llms.txt.
> For full documentation content, see https://docs.sqril.io/llms-full.txt.

# Execute Payout

POST https://api.sqril.com/executePayout
Content-Type: application/json

Executes payout with confirmed amount from a pending transaction.

**Authentication:**

- **REQUIRED**: Basic Auth only. Body-based credentials are deprecated and not supported.
    

**Key requirements:**

- `customer_id` is **required** and must:
    - be provided in request body,
        
    - not contain `/`,
        
    - exist under your account's `registered_customers`, and
        
    - match the `customer_id` bound to the transaction.
        
- Sender profile for execute is sourced from the registered customer record. **You do not need to send** **`sender`** **in executePayout.**
    

**Flow:**

1. **X-Idempotency-Key** header is required (unique per logical payout).
    
2. **HMAC (when configured):** If your account has `signing_secret`, send HMAC-SHA256 over JSON body (excluding `signature`) via `X-Signature` or body `signature`.
    
3. If idempotency key already has a successful stored 202 response, that response is replayed (with ownership/customer validation).
    
4. Loads transaction, validates account ownership, `customer_id` ownership, and **PENDING** status.
    
5. **Amount/currency lock:** if transaction already has saved amount/currency, `amount_confirmed` and `currency` must match exactly.
    
6. **partner_transaction_id:** can be set once if empty; otherwise must be omitted or the same value.
    
7. Validates required fields from `missing_fields`
    
8. API returns **202 Accepted** (with status `PROCESSING`). Final status is completed by provider/webhook updates.
    

**Request body:**

- Required: `tx_id`, `customer_id`, `amount_confirmed`, `currency`
    
- Optional: `partner_transaction_id`
    
- `sender` is not required for execute (derived from registered customer profile).
    

**Response (202 Accepted):**

- `status`, `tx_id`, `customer_id`, `message`, `exchange_rate`, `fee`, `percentage_fee`, `fixed_fee`, `amount`, `amount_usd`, `currency`
    
- Optional: `recipient`, `partner_transaction_id`, `updated_at`
    

**Precision:**

- `exchange_rate`: **10** decimal places
    
- USD fields (`fee`, `percentage_fee`, `fixed_fee`, `amount_usd`): **2** decimal places
    

**Error:**

- Returns 404 if `customer_id` is not found under your account.
    
- Returns 403 when transaction ownership does not match account/customer.

Reference: https://docs.sqril.io/sqril-saa-s-api/payout-endpoints/execute-payout

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: collection
  version: 1.0.0
paths:
  /executePayout:
    post:
      operationId: execute-payout
      summary: Execute Payout
      description: >-
        Executes payout with confirmed amount from a pending transaction.


        **Authentication:**


        - **REQUIRED**: Basic Auth only. Body-based credentials are deprecated
        and not supported.
            

        **Key requirements:**


        - `customer_id` is **required** and must:
            - be provided in request body,
                
            - not contain `/`,
                
            - exist under your account's `registered_customers`, and
                
            - match the `customer_id` bound to the transaction.
                
        - Sender profile for execute is sourced from the registered customer
        record. **You do not need to send** **`sender`** **in executePayout.**
            

        **Flow:**


        1. **X-Idempotency-Key** header is required (unique per logical payout).
            
        2. **HMAC (when configured):** If your account has `signing_secret`,
        send HMAC-SHA256 over JSON body (excluding `signature`) via
        `X-Signature` or body `signature`.
            
        3. If idempotency key already has a successful stored 202 response, that
        response is replayed (with ownership/customer validation).
            
        4. Loads transaction, validates account ownership, `customer_id`
        ownership, and **PENDING** status.
            
        5. **Amount/currency lock:** if transaction already has saved
        amount/currency, `amount_confirmed` and `currency` must match exactly.
            
        6. **partner_transaction_id:** can be set once if empty; otherwise must
        be omitted or the same value.
            
        7. Validates required fields from `missing_fields`
            
        8. API returns **202 Accepted** (with status `PROCESSING`). Final status
        is completed by provider/webhook updates.
            

        **Request body:**


        - Required: `tx_id`, `customer_id`, `amount_confirmed`, `currency`
            
        - Optional: `partner_transaction_id`
            
        - `sender` is not required for execute (derived from registered customer
        profile).
            

        **Response (202 Accepted):**


        - `status`, `tx_id`, `customer_id`, `message`, `exchange_rate`, `fee`,
        `percentage_fee`, `fixed_fee`, `amount`, `amount_usd`, `currency`
            
        - Optional: `recipient`, `partner_transaction_id`, `updated_at`
            

        **Precision:**


        - `exchange_rate`: **10** decimal places
            
        - USD fields (`fee`, `percentage_fee`, `fixed_fee`, `amount_usd`): **2**
        decimal places
            

        **Error:**


        - Returns 404 if `customer_id` is not found under your account.
            
        - Returns 403 when transaction ownership does not match
        account/customer.
      tags:
        - subpackage_payoutEndpoints
      parameters:
        - name: X-Idempotency-Key
          in: header
          required: false
          schema:
            type: string
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Payout Endpoints_Execute
                  Payout_Response_202
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostExecutepayoutRequestBadRequestError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostExecutepayoutRequestUnauthorizedError'
        '402':
          description: Payment Required
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/PostExecutepayoutRequestPaymentRequiredError
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostExecutepayoutRequestNotFoundError'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                tx_id:
                  type: string
                amount_confirmed:
                  type: integer
                currency:
                  type: string
                customer_id:
                  type: string
              required:
                - tx_id
                - amount_confirmed
                - currency
                - customer_id
servers:
  - url: https://api.sqril.com
  - url: https://your-app.com
components:
  schemas:
    ExecutePayoutPostResponsesContentApplicationJsonSchemaSender:
      type: object
      properties:
        name_first:
          type: string
        name_last:
          type: string
        ic:
          type: string
        ic_type:
          type: string
        country:
          type: string
        phone:
          type: string
        email:
          type: string
          format: email
      required:
        - name_first
        - name_last
        - ic
        - ic_type
        - country
        - phone
        - email
      title: ExecutePayoutPostResponsesContentApplicationJsonSchemaSender
    ExecutePayoutPostResponsesContentApplicationJsonSchemaRecipient:
      type: object
      properties:
        name:
          type: string
        account_no:
          type: string
        bank_no:
          type: string
      required:
        - name
        - account_no
        - bank_no
      title: ExecutePayoutPostResponsesContentApplicationJsonSchemaRecipient
    Payout Endpoints_Execute Payout_Response_202:
      type: object
      properties:
        status:
          type: string
        tx_id:
          type: string
        message:
          type: string
        exchange_rate:
          type: number
          format: double
        fee:
          type: number
          format: double
        percentage_fee:
          type: number
          format: double
        fixed_fee:
          type: number
          format: double
        amount:
          type: integer
        amount_usd:
          type: number
          format: double
        currency:
          type: string
        sender:
          $ref: >-
            #/components/schemas/ExecutePayoutPostResponsesContentApplicationJsonSchemaSender
        recipient:
          $ref: >-
            #/components/schemas/ExecutePayoutPostResponsesContentApplicationJsonSchemaRecipient
        partner_transaction_id:
          type: string
        updated_at:
          type: string
          format: date-time
      required:
        - status
        - tx_id
        - message
        - exchange_rate
        - fee
        - percentage_fee
        - fixed_fee
        - amount
        - amount_usd
        - currency
        - sender
        - recipient
        - partner_transaction_id
        - updated_at
      title: Payout Endpoints_Execute Payout_Response_202
    PostExecutepayoutRequestBadRequestError:
      type: object
      properties:
        error:
          type: string
        error_code:
          type: string
      required:
        - error
        - error_code
      title: PostExecutepayoutRequestBadRequestError
    PostExecutepayoutRequestUnauthorizedError:
      type: object
      properties:
        error:
          type: string
      required:
        - error
      title: PostExecutepayoutRequestUnauthorizedError
    PostExecutepayoutRequestPaymentRequiredError:
      type: object
      properties:
        error:
          type: string
        available:
          type: integer
        required:
          type: integer
      required:
        - error
        - available
        - required
      title: PostExecutepayoutRequestPaymentRequiredError
    PostExecutepayoutRequestNotFoundError:
      type: object
      properties:
        error:
          type: string
      required:
        - error
      title: PostExecutepayoutRequestNotFoundError

```

## SDK Code Examples

```python Success - 202 Accepted
import requests

url = "https://api.sqril.com/executePayout"

headers = {
    "X-Idempotency-Key": "{{tx_id}}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript Success - 202 Accepted
const url = 'https://api.sqril.com/executePayout';
const options = {
  method: 'POST',
  headers: {'X-Idempotency-Key': '{{tx_id}}', 'Content-Type': 'application/json'},
  body: undefined
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Success - 202 Accepted
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sqril.com/executePayout"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("X-Idempotency-Key", "{{tx_id}}")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Success - 202 Accepted
require 'uri'
require 'net/http'

url = URI("https://api.sqril.com/executePayout")

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

request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '{{tx_id}}'
request["Content-Type"] = 'application/json'

response = http.request(request)
puts response.read_body
```

```java Success - 202 Accepted
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sqril.com/executePayout")
  .header("X-Idempotency-Key", "{{tx_id}}")
  .header("Content-Type", "application/json")
  .asString();
```

```php Success - 202 Accepted
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sqril.com/executePayout', [
  'headers' => [
    'Content-Type' => 'application/json',
    'X-Idempotency-Key' => '{{tx_id}}',
  ],
]);

echo $response->getBody();
```

```csharp Success - 202 Accepted
using RestSharp;

var client = new RestClient("https://api.sqril.com/executePayout");
var request = new RestRequest(Method.POST);
request.AddHeader("X-Idempotency-Key", "{{tx_id}}");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
```

```swift Success - 202 Accepted
import Foundation

let headers = [
  "X-Idempotency-Key": "{{tx_id}}",
  "Content-Type": "application/json"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sqril.com/executePayout")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Success - 202 (with missing_fields provided)
import requests

url = "https://api.sqril.com/executePayout"

headers = {
    "X-Idempotency-Key": "{{tx_id}}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript Success - 202 (with missing_fields provided)
const url = 'https://api.sqril.com/executePayout';
const options = {
  method: 'POST',
  headers: {'X-Idempotency-Key': '{{tx_id}}', 'Content-Type': 'application/json'},
  body: undefined
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Success - 202 (with missing_fields provided)
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sqril.com/executePayout"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("X-Idempotency-Key", "{{tx_id}}")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Success - 202 (with missing_fields provided)
require 'uri'
require 'net/http'

url = URI("https://api.sqril.com/executePayout")

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

request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '{{tx_id}}'
request["Content-Type"] = 'application/json'

response = http.request(request)
puts response.read_body
```

```java Success - 202 (with missing_fields provided)
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sqril.com/executePayout")
  .header("X-Idempotency-Key", "{{tx_id}}")
  .header("Content-Type", "application/json")
  .asString();
```

```php Success - 202 (with missing_fields provided)
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sqril.com/executePayout', [
  'headers' => [
    'Content-Type' => 'application/json',
    'X-Idempotency-Key' => '{{tx_id}}',
  ],
]);

echo $response->getBody();
```

```csharp Success - 202 (with missing_fields provided)
using RestSharp;

var client = new RestClient("https://api.sqril.com/executePayout");
var request = new RestRequest(Method.POST);
request.AddHeader("X-Idempotency-Key", "{{tx_id}}");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);
```

```swift Success - 202 (with missing_fields provided)
import Foundation

let headers = [
  "X-Idempotency-Key": "{{tx_id}}",
  "Content-Type": "application/json"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sqril.com/executePayout")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

```python Payout Endpoints_Execute Payout_example
import requests

url = "https://api.sqril.com/executePayout"

payload = {
    "tx_id": "{{tx_id}}",
    "amount_confirmed": 200000,
    "currency": "VND",
    "customer_id": "{{customer_id}}"
}
headers = {
    "X-Idempotency-Key": "{{tx_id}}",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Payout Endpoints_Execute Payout_example
const url = 'https://api.sqril.com/executePayout';
const options = {
  method: 'POST',
  headers: {'X-Idempotency-Key': '{{tx_id}}', 'Content-Type': 'application/json'},
  body: '{"tx_id":"{{tx_id}}","amount_confirmed":200000,"currency":"VND","customer_id":"{{customer_id}}"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Payout Endpoints_Execute Payout_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sqril.com/executePayout"

	payload := strings.NewReader("{\n  \"tx_id\": \"{{tx_id}}\",\n  \"amount_confirmed\": 200000,\n  \"currency\": \"VND\",\n  \"customer_id\": \"{{customer_id}}\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency-Key", "{{tx_id}}")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Payout Endpoints_Execute Payout_example
require 'uri'
require 'net/http'

url = URI("https://api.sqril.com/executePayout")

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

request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '{{tx_id}}'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tx_id\": \"{{tx_id}}\",\n  \"amount_confirmed\": 200000,\n  \"currency\": \"VND\",\n  \"customer_id\": \"{{customer_id}}\"\n}"

response = http.request(request)
puts response.read_body
```

```java Payout Endpoints_Execute Payout_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sqril.com/executePayout")
  .header("X-Idempotency-Key", "{{tx_id}}")
  .header("Content-Type", "application/json")
  .body("{\n  \"tx_id\": \"{{tx_id}}\",\n  \"amount_confirmed\": 200000,\n  \"currency\": \"VND\",\n  \"customer_id\": \"{{customer_id}}\"\n}")
  .asString();
```

```php Payout Endpoints_Execute Payout_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sqril.com/executePayout', [
  'body' => '{
  "tx_id": "{{tx_id}}",
  "amount_confirmed": 200000,
  "currency": "VND",
  "customer_id": "{{customer_id}}"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-Idempotency-Key' => '{{tx_id}}',
  ],
]);

echo $response->getBody();
```

```csharp Payout Endpoints_Execute Payout_example
using RestSharp;

var client = new RestClient("https://api.sqril.com/executePayout");
var request = new RestRequest(Method.POST);
request.AddHeader("X-Idempotency-Key", "{{tx_id}}");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"tx_id\": \"{{tx_id}}\",\n  \"amount_confirmed\": 200000,\n  \"currency\": \"VND\",\n  \"customer_id\": \"{{customer_id}}\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Payout Endpoints_Execute Payout_example
import Foundation

let headers = [
  "X-Idempotency-Key": "{{tx_id}}",
  "Content-Type": "application/json"
]
let parameters = [
  "tx_id": "{{tx_id}}",
  "amount_confirmed": 200000,
  "currency": "VND",
  "customer_id": "{{customer_id}}"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sqril.com/executePayout")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```