⭐️ Local Payout API Integration Guide

How to integrate Pivot Local Payout API

This guide explains the complete integration flow for sending local payouts using the Pivot Payment API. It covers authentication, beneficiary validation, payout creation, webhook handling, and payout status reconciliation.

This page provides an end-to-end workflow. For full endpoint specifications, refer to the individual API references.

Overview

Pivot Local Payout API allows merchants to transfer funds from their Pivot balance to beneficiary bank accounts in Indonesia.

A typical payout integration consists of the following steps:

1. Authenticate API requests

2. Check available payout balance

3. Validate beneficiary bank account (Inquiry Account)

4. Create payout transaction

5. Receive payout status via webhook callback

6. Retrieve payout status for reconciliation (optional)

---

Prerequisites

Before integrating the payout API, ensure that:

• Your merchant account has been activated for Local Payout.

• You have received the following credentials from Pivot:

Credential	Description
Client Key	Used to authenticate requests
Client Secret	Used to sign requests
Merchant ID	Unique identifier for your account

You should also configure:

• A secure webhook endpoint to receive payout callbacks

• Proper idempotency handling to avoid duplicate payouts

---

Base URL

Production

https://api.pivot-payment.com

Sandbox

https://api-stg.pivot-payment.com

---

Authentication

All API requests must include authentication headers. A valid access token must be included in the Authorization header when sending requests to the Pivot API.

Endpoint reference:

Authentication

Example headers:

X-MERCHANT-ID: [Your Client ID]
X-MERCHANT-SECRET: [Your Client Secret]

Example request:

{
    "grantType": "client_credentials"
}

Example response:

{
    "code": "00",
    "message": "Success",
    "data": {
        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJiYWNrZW5kLXBvcnRhbCIsInN1YiI6IjkyMmUzOWFiLTc1NjUtNDlmNi1iODRmLWZiNTYxMjI4MjFhZSIsImV4cCI6MTcxNDAyODE0MywiY2xpZW50SWQiOiI5MjJlMzlhYi03NTY1LTQ5ZjYtYjg0Zi1mYjU2MTIyODIxYWUiLCJtZXJjaGFudElkIjoiOTIyZTM5YWItNzU2NS00OWY2LWI4NGYtZmI1NjEyMjgyMWFlIn0.EkxckAJEcB4fgVU97mQC5eooBwQ7vhexzksafyUgOPU",
        "expiresIn": "900",
        "tokenType": "Bearer"
    }
}

Access tokens expire after 900 seconds (15 minutes). You must request a new access token once the current token expires.

---

Recommended Integration Flow

The recommended payout flow is shown below.

Merchant System
      │
      │
      ├── Check Balance
      │
      ├── Inquiry Account (validate beneficiary)
      │
      ├── Create Payout
      │
      ├── Receive Webhook Callback
      │
      └── Retrieve Payout Status (optional)

---

Step 1 — Check Payout Balance

Before creating a payout, ensure that your Pivot balance is sufficient to cover the transaction amount. If the balance is insufficient, the payout request will not be processed. The transaction will appear in the dashboard under Local Payout → Need Action → Waiting for Top Up, where you may retry the payout after topping up your balance or cancel the transaction.

Endpoint reference:

Payout Balance

Example request:

GET /v1/payouts/balance?currency=IDR

Example response:

{
  "code": "00",
  "message": "Success",
  "data": {
    "availableBalance": {
      "currency": "IDR",
      "value": "4440916697.16"
    }
  }
}

---

Step 2 — Validate Beneficiary Account

Before creating a payout, validate the beneficiary account using Inquiry Account.

This ensures:

• the bank account exists

• the account name matches the expected beneficiary

Endpoint reference:

Inquiry Account

Example request:

{
  "channelCode": "BCA",
  "channelInformation": {
    "accountNumber": "999966660001",
    "accountName": "Reforza Pivot"
  }
}

Example response:

{
  "account_name": "BUDI SANTOSO",
  "bank_code": "014",
  "account_number": "1234567890",
  "status": "VALID"
}

You should display the returned account_name to your user for confirmation.

---

Step 3 — Create Payout

Once the beneficiary is validated, create the payout transaction. You have two options to create a payout:

• Using inquiryId, or

• Using channel information

Endpoint reference:

Create Payout

Example request using inquiryId:

{
  "payouts": [
    {
      "referenceId": "1999",
      "inquiryId": "d6a46a2c-1b26-40c5-9ca3-e063e69635a0",
      "amount": {
        "value": "100000",
        "currency": "IDR"
      },
      "description": "test Reforza Pivot"
    }
  ]
}

Example request using channel information:

{
  "payouts": [
    {
      "referenceId": "999",
      "channelCode": "BRI",
      "channelInformation": {
        "accountNumber": "888801000157508",
        "accountName": "Reforza Pivot"
      },
      "amount": {
        "value": "100000",
        "currency": "IDR"
      },
      "description": "test Reforza Pivot"
    }
  ]
}

Note: For the full list of channel codes, refer to Channel Codes.

Example response:

{
  "code": "00",
  "message": "Success",
  "data": {
    "created": "2024-05-13T08:21:44.967496435Z",
    "merchantId": "922e39ab-7565-49f6-b84f-fb56122821ae",
    "payouts": [
      {
        "amount": {
          "currency": "IDR",
          "value": "100000"
        },
        "inquiryId": "",
        "channelCode": "BRI",
        "channelInformation": {
          "accountName": "Reforza Pivot",
          "accountNumber": "888801000157508"
        },
        "description": "test Reforza Pivot",
        "referenceId": "999"
      }
    ],
    "status": "IN_PROGRESS",
    "updated": "2024-05-13T08:21:44.967496538Z",
    "uuid": "d6a46a2c-1b26-40c5-9ca3-e063e69635a0"
  }
}

Important notes:

• reference_id must be unique for each payout.

• Use idempotency to prevent duplicate transactions.

---

Step 4 — Handle Webhook Callback

Pivot sends a webhook callback when the payout status is updated.

Typical payout statuses:

Status	Meaning
PROCESSING	Payout is being processed
SUCCESS	Funds successfully transferred
FAILED	Payout failed
DELAYED	Payout is taking longer than expected to process

Example webhook payload for bulk payout:

{
  "event": "PAYOUT.DONE",
  "data": {
    "uuid": "d6a46a2c-1b26-40c5-9ca3-e063e69635a0",
    "merchantId": "922e39ab-7565-49f6-b84f-fb56122821ae",
    "payoutResults": {
      "totalPendingCount": 0,
      "totalPendingAmount": 0,
      "totalSuccessCount": 1,
      "totalSuccessAmount": 100000,
      "totalFailedCount": 0,
      "totalFailedAmount": 0,
      "totalCancelledCount": 0,
      "totalCancelledAmount": 0
    },
    "status": "DONE"
  }
}

Example webhook payload for single payout:

{
  "event": "PAYOUT.SUCCESS",
  "data": {
    "uuid": "d6a46a2c-1b26-40c5-9ca3-e063e69635a0",
    "merchantId": "922e39ab-7565-49f6-b84f-fb56122821ae",
    "payouts": {
      "referenceId": "TestReforzaPivot001",
      "amount": {
        "currency": "IDR",
        "value": "100000"
      },
      "status": "SUCCESS",
      "reason": ""
    }
  }
}

Your webhook endpoint should:

1. Verify the callback authenticity

2. Update payout status in your system

3. Return HTTP 200 to acknowledge receipt

Example response:

HTTP 200 OK

If your endpoint returns an error or timeout, Pivot may retry sending the webhook. For more details on the retry mechanism, refer to Callback.

---

Step 5 — Retrieve Payout Status (Optional)

You may retrieve payout status via API for reconciliation or if webhook delivery fails.

Endpoint reference:

Retrieve Payout

Example request:

GET /v1/payouts/{uuid}

Example response:

{
  "code": "00",
  "message": "Success",
  "data": {
    "created": "2024-05-13T08:21:45Z",
    "merchantId": "922e39ab-7565-49f6-b84f-fb56122821ae",
    "payoutResults": {
      "totalFailedAmount": 0,
      "totalFailedCount": 0,
      "totalPendingAmount": 0,
      "totalPendingCount": 0,
      "totalSuccessAmount": 100000,
      "totalSuccessCount": 1,
      "totalCancelledCount": 0,
      "totalCancelledAmount": 0
    },
    "payouts": [
      {
        "amount": {
          "currency": "IDR",
          "value": "100000"
        },
        "channelCode": "BRI",
        "channelInformation": {
          "accountName": "Reforza Pivot",
          "accountNumber": "888801000157508"
        },
        "created": "2024-05-13T08:21:45Z",
        "inquiryId": "d6a46a2c-1b26-40c5-9ca3-e063e69635a0",
        "description": "test Reforza Pivot",
        "referenceId": "999",
        "status": "SUCCESS",
        "reason": "",
        "updated": "2024-05-13T08:21:46Z"
      }
    ],
    "status": "DONE",
    "updated": "2024-05-13T08:21:46Z",
    "uuid": "d6a46a2c-1b26-40c5-9ca3-e063e69635a0"
  },
  "pagination": {
    "page": 1,
    "perPage": 20,
    "totalItems": 1,
    "totalPages": 1
  }
}

To retrieve the details of a specific payout, refer to Retrieve a Single Payout Request.

Example request:

GET /v1/payouts/:{uuid}?referenceId=:{referenceId}

Example response:

{
  "code": "00",
  "message": "Success",
  "data": {
    "merchantId": "922e39ab-7565-49f6-b84f-fb56122821ae",
    "payoutResults": {
      "totalFailedAmount": 0,
      "totalFailedCount": 0,
      "totalPendingAmount": 0,
      "totalPendingCount": 0,
      "totalSuccessAmount": 100000,
      "totalSuccessCount": 1,
      "totalCancelledCount": 0,
      "totalCancelledAmount": 0
    },
    "payouts": {
      "amount": {
        "currency": "IDR",
        "value": "100000"
      },
      "channelCode": "BRI",
      "channelInformation": {
        "accountName": "Reforza Pivot",
        "accountNumber": "888801000157508"
      },
      "created": "2024-05-13T08:21:45Z",
      "inquiryId": "d6a46a2c-1b26-40c5-9ca3-e063e69635a0",
      "description": "test Reforza Pivot",
      "referenceId": "999",
      "status": "SUCCESS",
      "reason": "",
      "updated": "2024-05-13T08:21:46Z"
    },
    "uuid": "d6a46a2c-1b26-40c5-9ca3-e063e69635a0"
  }
}

---

Idempotency

To prevent duplicate transaction processing, all payout requests must include the X-REQUEST-ID header. Pivot uses this value to ensure that the same request is not processed multiple times.

If the same X-REQUEST-ID is received more than once within the validity period, Pivot will treat the request as the same transaction and return the original response instead of creating a new payout.

X-REQUEST-ID Requirements

The X-REQUEST-ID value must meet the following requirements:

• Must contain only alphanumeric characters

• Minimum length: 16 characters

• Maximum length: 36 characters

• The ID remains valid for 24 hours

After 24 hours, the same X-REQUEST-ID may be reused for a new transaction request.

Example Header:

X-REQUEST-ID: a1b2c3d4e5f6g7h8

Tips

Further measure to prevent duplicate payouts:

• Do not retry payouts blindly if the transaction has not reached final status

• Always check payout status before retrying

---

Error Handling

Common payout failure scenarios include:

Error	Cause
Invalid account	Beneficiary account is invalid or doesn't exist
Declined due to beneficiary limit	Beneficiary account has already reached the daily limit
Failed to process by Bank Network	Bank network failed to process the transaction

Refer to the Response Codes and Failure Reasons section for full error mappings.

---

Common Integration Questions

What happens if the webhook fails?

If your webhook endpoint fails to respond with HTTP 200, Pivot will retry sending the callback. You should ensure your endpoint is highly available.

---

Can I retry a payout?

Do not retry immediately. Always retrieve the payout status first to avoid duplicate transfers.

---

Should I rely on webhook or API status?

Webhook is the primary mechanism for status updates. Retrieve payout status only for reconciliation or webhook failures.

---

Do I need to perform Inquiry Account before every payout?

Yes. This ensures the beneficiary account is valid and prevents payout failures.

---

How do I avoid duplicate payouts?

Use a unique reference_id for each payout and implement idempotency logic in your system.

---

API References

For full endpoint specifications, refer to:

• Payout Balance

• Inquiry Account

• Create Payout

• Retrieve Payout

• Callback

• Response Codes and Failure Reasons

• Test Scenarios

• Channel Codes