> ## Documentation Index
> Fetch the complete documentation index at: https://docs.singapay.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Transfer funds from your Singapay balance directly to customers' e-wallets — OVO, Dana, ShopeePay, GoPay, and more.

The E-Wallet Top Up API lets you send funds from your Singapay account to any supported Indonesian e-wallet. Use it to automate cashback, refunds, rewards, or seller payouts directly to customers' e-wallet balances — no bank account required.

<Info>
  This is a **Money Out** operation. Each top-up debits funds from your Singapay Payment Gateway balance and credits the destination e-wallet account.
</Info>

<CardGroup cols={4}>
  <Card title="OVO" icon="wallet">
    Top up OVO balance directly.
  </Card>

  <Card title="Dana" icon="wallet">
    Transfer to Dana accounts.
  </Card>

  <Card title="ShopeePay" icon="wallet">
    Fund ShopeePay wallets.
  </Card>

  <Card title="GoPay & more" icon="wallet">
    GoPay and other supported providers.
  </Card>
</CardGroup>

***

## Recommended flow

```mermaid theme={null}
sequenceDiagram
    participant M as Merchant System
    participant S as SingaPay API
    participant E as E-Wallet Provider

    M->>S: Account Inquiry (phone number + provider)
    S-->>M: Account holder name, limits & fee quote

    M->>M: Present confirmation to user

    M->>S: Trigger Transfer (validated account + amount)
    S->>S: Debit Singapay balance
    S->>E: Dispatch top-up to provider
    S-->>M: reference_number + status (pending/success/failed)

    M->>S: Inquiry Status (reference_number)
    S-->>M: Final transaction status
```

<Steps>
  <Step title="Inquiry account">
    Call **E-Wallet Top Up — Account Inquiry** with the customer's e-wallet phone number and provider. Singapay validates the account via Shanghai Core and returns the registered account holder name plus applicable limits and fee quote. Present this to the user for confirmation.
  </Step>

  <Step title="Trigger top-up">
    Once confirmed, call **E-Wallet Top Up — Trigger Transfer** with the validated account details and amount. Singapay debits your balance and dispatches the top-up job to the provider. A `reference_number` is returned to track the transaction.
  </Step>

  <Step title="Inquiry status">
    Use **E-Wallet Top Up — Inquiry Status** with the `reference_number` to verify the final outcome — especially for transactions that remain in `pending` state.
  </Step>
</Steps>

***

## Transaction status

| Status    | Description                                                     |
| --------- | --------------------------------------------------------------- |
| `pending` | Top-up initiated, awaiting processing by the e-wallet provider. |
| `success` | Funds successfully credited to the destination e-wallet.        |
| `failed`  | Top-up failed — check the response code for the reason.         |

***

## Important notes

<AccordionGroup>
  <Accordion title="Always inquiry before transferring" icon="shield-check">
    Always call **Account Inquiry** before initiating a top-up. This validates the destination e-wallet account, confirms the holder name, and returns the fee and net amount — so the user can confirm before funds are debited.
  </Accordion>

  <Accordion title="Provider-specific limits" icon="sliders">
    Each e-wallet provider has its own minimum and maximum top-up limits. These are returned in the Account Inquiry response — always check before submitting a transfer to avoid validation errors.
  </Accordion>

  <Accordion title="Signature required for transfers" icon="lock">
    The **Trigger Transfer** endpoint requires additional `X-Signature` and `X-Timestamp` headers using internal signing rules — separate from standard Bearer token auth. See [Authentication](/api-reference/authentication) for signing requirements.
  </Accordion>

  <Accordion title="Reference number for tracking" icon="fingerprint">
    Store the `reference_number` returned from the Trigger Transfer call. Use it with **Inquiry Status** to safely check the outcome and handle retries without creating duplicate top-ups.
  </Accordion>

  <Accordion title="Pending status handling" icon="clock">
    For transactions that return `pending`, use **Inquiry Status** to refresh the status. If a `vendor_reference_no` exists on a pending record, Singapay will attempt to refresh the status from the provider — timeouts return response code `SP005`.
  </Accordion>
</AccordionGroup>

***

## Available endpoints

<CardGroup cols={3}>
  <Card title="Account Inquiry" icon="user-check" href="./inquiry-account">
    Validate the destination e-wallet account and get limits and fee quote before transferring.
  </Card>

  <Card title="Trigger Transfer" icon="paper-plane" href="./trigger-top-up">
    Initiate the top-up and transfer funds from your Singapay balance to the e-wallet.
  </Card>

  <Card title="Inquiry Status" icon="magnifying-glass" href="./inquiry-status">
    Query the current status of a top-up transaction by reference number.
  </Card>
</CardGroup>

<Note>
  All endpoints require `Authorization: Bearer <token>` and `X-PARTNER-ID` on every request. The Trigger Transfer endpoint additionally requires `X-Signature` and `X-Timestamp`. See [Authentication](/api-reference/authentication) for details.
</Note>