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

# Payout API

> Use Rampnow's payout APIs to create beneficiaries, get quotes and trigger cross-border transfer orders.

Rampnow's Payout API lets you:

* Create and manage **beneficiaries** (end recipients)
* Request **transfer quotes** (crypto → fiat)
* Create **transfer orders** funded in USDC/USDT
* Retrieve beneficiary and transfer details for reconciliation

These endpoints are used across all payout products: **payroll, vendor payments, remittances and treasury payouts**.

<Note>
  All payouts are funded in **USDC or USDT** and delivered via local rails (IMPS, ACH/SWIFT, SEPA and other supported domestic networks).
</Note>

## High-Level Flow

<Steps>
  <Step title="Create Remitter" icon="user-plus">
    Use `CreateRemitter` to register the sender with their profile and details. Response returns `userUid`.
  </Step>

  <Step title="(Optional) Retrieve Remitter" icon="magnifying-glass">
    Use `GetRemitter` to check the status of the remitter being added.
  </Step>

  <Step title="Create Beneficiary" icon="user-plus">
    Use `CreateBeneficiary` to register the receiver with their profile and bank account details. Response returns `userUid` and `walletUid`.
  </Step>

  <Step title="(Optional) Retrieve Beneficiary" icon="magnifying-glass">
    Use `GetBeneficiary` to check status, attached wallets and bank account details.
  </Step>

  <Step title="Get Transfer Quote" icon="calculator">
    Use `GetTransferOrderQuote` to preview FX, source amount and destination amount for a given corridor and currency pair.
  </Step>

  <Step title="Create Transfer Order" icon="paper-plane">
    Use `CreateTransferOrder` to initiate the payout using the `walletUid` from the beneficiary, `remitterUid` from remitter and your source/destination currency setup. Response includes payment instructions (bank or crypto), status, partner fee breakdown and expiry.
  </Step>

  <Step title="Get Transfer Order Status" icon="paper-plane">
    Use `GetTransferOrder` API to retrieve the latest status of any transfer using the **Transfer Order ID** returned by `CreateTransferOrder` API.
  </Step>
</Steps>

***

## 1. Create Remitter

Create a Remitter (sender) with user data.

```http Request theme={null}
POST https://api.sandbox.rampnow.io/api/partner/v1/ext/transfer_order/remitter
```

```json Request body expandable theme={null}
{
  "user": {
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+14155552671",
    "dateOfBirth": "1990-05-15",
    "gender": 1,
    "country": "US",
    "address": {
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "subDivision": "",
      "country": "US",
      "postalCode": "94105"
    },
    "userType": null,
    "businessDetail": null
  },
  "orderType": 8,
  "capability": 0,
  "idDocs": [
    {
      "docSetType": 12,
      "documentId": "P12345678",
      "frontSideUrl": "https://storage.example.com/docs/passport_front.jpg",
      "backSideUrl": "https://storage.example.com/docs/passport_back.jpg",
      "issuingCountry": "US",
      "expiration": "2030-06-30T00:00:00Z"
    }
  ]
}
```

## Key concepts:

* user – legal person data
* idDocs – optional document set for enhanced checks (front/back URLs, etc.)

```json Response theme={null}
{
  "code": 123,
  "data": {
    "uid": "usr_x9y8z7w6v5",
    "type": 0,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "country": "US",
    "capabilities": [
      {
        "capability": 0,
        "status": 2,
        "actions": [
          {
            "type": "accept_tos",
            "title": "Accept Terms of Service",
            "description": "Please accept the terms before proceeding",
            "url": "https://provider.example.com/tos/abc123"
          }
        ]
      }
    ]
  },
  "message": "<string>",
  "traceId": "<string>"
}
```

* uid – internal identifier for the remitter user

## 2. Get Remitter

Retrieve an existing remitter and all its capabilities.

```http http theme={null}
GET https://api.sandbox.rampnow.io/api/partner/v1/ext/transfer_order/remitter/{uid}
```

### Path parameter:

* uid – the uid returned from CreateRemitter

```json Response expandable theme={null}
{
  "code": 123,
  "data": {
    "uid": "usr_x9y8z7w6v5",
    "type": 0,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "country": "US",
    "capabilities": [
      {
        "capability": 0,
        "status": 2,
        "actions": [
          {
            "type": "accept_tos",
            "title": "Accept Terms of Service",
            "description": "Please accept the terms before proceeding",
            "url": "https://provider.example.com/tos/abc123"
          }
        ]
      }
    ]
  },
  "message": "<string>",
  "traceId": "<string>"
}
```

Use this endpoint to:

* Check beneficiary status (e.g. active / pending / blocked)
* Inspect attached wallets (bank or crypto accounts)
* Retrieve the wallet uid if you need it for a new transfer

## 1. Create Beneficiary

Create a beneficiary wallet (end recipient) with user data and one linked bank account.

```http Request theme={null}
POST https://api.sandbox.rampnow.io/api/partner/v1/ext/transfer_order/beneficiary/wallet
```

```json Request body expandable theme={null}
{
  "orderType": "sendout",
  "userUid": "user-id",
  "bankAccount": {
    "accountNumber": "<string>",
    "accountType": "<string>",
    "address": "<string>",
    "bankName": "<string>",
    "bic": "<string>",
    "branchName": "<string>",
    "country": "AD",
    "currency": "AAAFISH",
    "email": "<string>",
    "iban": "<string>",
    "name": "<string>",
    "phone": "<string>",
    "taxId": "<string>",
    "transferCode": "<string>",
    "uid": "<string>"
  },
  "idDocs": [
    {
      "backSideUrl": "<string>",
      "docSetType": "unknown",
      "documentId": "<string>",
      "frontSideUrl": "<string>"
    }
  ],
  "user": {
    "address": {
      "city": "<string>",
      "country": "AD",
      "line1": "<string>",
      "line2": "<string>",
      "postalCode": "<string>",
      "state": "<string>",
      "subDivision": "<string>"
    },
    "country": "AD",
    "userType": "business",
    "dateOfBirth": "<string>",
    "email": "<string>",
    "firstName": "<string>",
    "gender": "unknown",
    "lastName": "<string>",
    "phone": "<string>"
  }
}
```

## Key concepts:

* user – legal person data
* bankAccount – payout destination (IBAN or local account)
* idDocs – optional document set for enhanced checks (front/back URLs, etc.)

```json Response theme={null}
{
  "code": 123,
  "data": {
    "uid": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "country": "<string>",
    "capabilities": [
      {
        "capability": "sepa",
        "status": "approved",
        "actions": [
          {
            "type": "doc_upload",
            "title": "<string>",
            "description": "<string>",
            "url": "<string>"
          }
        ]
      }
    ],
    "userUid": "<string>",
    "walletUid": "<string>",
    "address": {
      "line1": "<string>",
      "line2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "subDivision": "<string>",
      "country": "<string>",
      "postalCode": "<string>"
    },
    "wallet": {
      "uid": "<string>",
      "bankAccountDetail": {
        "name": "John Doe",
        "iban": "GB29NWBK60161331926819",
        "bic": "NWBKGB2L",
        "accountNumber": "31926819",
        "email": "john.doe@example.com",
        "phone": {
          "countryCode": "+44",
          "number": "7911123456"
        },
        "accountType": "checking",
        "address": "123 Main Street, London, UK",
        "bankName": "National Westminster Bank",
        "branchName": "London West End",
        "transferCode": "60-16-13",
        "taxId": "AB123456C",
        "currency": "GBP",
        "country": "GB"
      }
    }
  },
  "message": "<string>",
  "traceId": "<string>"
}
```

* userUid – internal identifier for the beneficiary user
* walletUid – identifier used later in CreateTransferOrder to send payouts to this beneficiary

## 2. Get Beneficiary

Retrieve an existing beneficiary and all linked payout wallets.

```http http theme={null}
GET https://api.sandbox.rampnow.io/api/partner/v1/ext/transfer_order/beneficiary/wallet/{uid}
```

### Path parameter:

* uid – the userUid returned from CreateBeneficiary

```json Response expandable theme={null}
{
  "code": 123,
  "data": {
    "uid": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "country": "<string>",
    "capabilities": [
      {
        "capability": "sepa",
        "status": "approved",
        "actions": [
          {
            "type": "doc_upload",
            "title": "<string>",
            "description": "<string>",
            "url": "<string>"
          }
        ]
      }
    ],
    "userUid": "<string>",
    "walletUid": "<string>",
    "address": {
      "line1": "<string>",
      "line2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "subDivision": "<string>",
      "country": "<string>",
      "postalCode": "<string>"
    },
    "wallet": {
      "uid": "<string>",
      "bankAccountDetail": {
        "name": "John Doe",
        "iban": "GB29NWBK60161331926819",
        "bic": "NWBKGB2L",
        "accountNumber": "31926819",
        "email": "john.doe@example.com",
        "phone": {
          "countryCode": "+44",
          "number": "7911123456"
        },
        "accountType": "checking",
        "address": "123 Main Street, London, UK",
        "bankName": "National Westminster Bank",
        "branchName": "London West End",
        "transferCode": "60-16-13",
        "taxId": "AB123456C",
        "currency": "GBP",
        "country": "GB"
      }
    }
  },
  "message": "<string>",
  "traceId": "<string>"
}
```

Use this endpoint to:

* Check beneficiary status (e.g. active / pending / blocked)
* Inspect attached wallets (bank or crypto accounts)
* Retrieve the wallet uid if you need it for a new transfer

## 3. Get Transfer Order Quote

Get indicative pricing and FX details for a potential transfer order.

<Note>
  Use this before creating a transfer order so you can show the user what they will pay and what the recipient will receive.
</Note>

```http Request theme={null}
GET https://api.sandbox.rampnow.io/api/partner/v1/ext/transfer_order/quote
```

<Note>
  * Pass your quote parameters as query string (source/destination currency, chain, amount, etc.).
  * Exact query parameters can be aligned with your implementation.
</Note>

```json Response expandable theme={null}
{
  "code": 123,
  "data": {
    "orderType": "sendout",
    "dstamount": "<string>",
    "dstchain": "abstract",
    "dstcurrency": "AAAFISH",
    "exchangeRate": "<string>",
    "srcamount": "<string>",
    "srcchain": "abstract",
    "srccurrency": "AAAFISH",
    "partnerPctFee": "<string>",
    "partnerFixedFee": "<string>"
  },
  "message": "<string>",
  "traceId": "<string>"
}
```

### Fields:

* srcamount / srccurrency / srcchain – the crypto side (typically USDC/USDT)
* dstamount / dstcurrency / dstchain – the payout side (INR, USD, EUR, PHP, IDR, etc.)
* exchangeRate – applied rate from source to destination

## 4. Create Transfer Order

Create a transfer order that will be funded in USDC/USDT and paid out to a specific beneficiary wallet.

```http Request theme={null}
POST https://api.sandbox.rampnow.io/api/partner/v1/ext/transfer_order
```

```json Request Body expandable theme={null}
{
  "orderType": "sendout",
  "apiKey": "<string>",
  "dstAmount": "<string>",
  "dstChain": "fiat",
  "dstCurrency": "EUR",
  "reference": "<string>",
  "srcChain": "base",
  "srcCurrency": "USDC",
  "walletUid": "<string>",
  "partnerPctFee": "<string>",
  "partnerFixedFee": "<string>"
}
```

### Key fields:

* apiKey – your partner API key (authentication / routing)
* walletUid – from CreateBeneficiary or GetBeneficiary
* srcCurrency / srcChain – crypto funding (USDC or USDT on a supported chain)
* dstCurrency / dstChain – payout currency & corridor
* dstAmount – amount to be delivered to the beneficiary
* reference – your internal reference for reconciliation

```json Response expandable theme={null}
{
  "code": 123,
  "data": {
    "uid": "tord_a1b2c3d4e5f6",
    "status": 1,
    "amount": "100.00",
    "currency": "USD",
    "expiry": 1744300800,
    "payment": {
      "status": 2,
      "redirectUrl": null,
      "bankTxnInfo": {
        "fee": "1.50",
        "message": "Transfer reference: REF123456",
        "sender": {
          "accountNumber": "000123456789",
          "routingNumber": "021000021",
          "bankName": "Chase Bank"
        },
        "receiver": {
          "accountNumber": "000987654321",
          "routingNumber": "021000021",
          "bankName": "Rampnow Bank"
        }
      }
    },
    "feeDetails": [
      {
        "type": "platform_fee",
        "fee": "1.50",
        "currency": "USD",
        "isInclusive": true
      }
    ]
  },
  "message": "<string>",
  "traceId": "<string>"
}
```

## 5. Get Transfer Status (Using `uid`)

You can retrieve the latest status of any payout using the **uid** returned by all Rampnow endpoints (`CreateTransferOrder`, webhooks and error responses).\
This gives partners a deterministic way to track payout states across funding → FX conversion → settlement.

<Info>
  `uid` is globally unique and can be used to trace a payout through support, logs and audit flows.
</Info>

### Endpoint

```http Request theme={null}
GET /api/partner/v1/ext/transfer_order/:uid
```

```json Response expandable theme={null}
{
  "code": 0,
  "data": {
    "createdAt": "2026-04-10T08:30:00Z",
    "updatedAt": "2026-04-10T08:45:00Z",
    "uid": "tord_a1b2c3d4e5f6",
    "status": 3,
    "orderType": 1,
    "payinMode": 9,
    "payoutMode": 15,
    "paymentStatus": 4,
    "srcChain": "",
    "srcCurrency": "USD",
    "srcAmount": "100.00",
    "dstChain": "ethereum",
    "dstCurrency": "USDC",
    "dstAmount": "98.25",
    "baseAmount": "100.00",
    "baseCurrency": "USD",
    "country": "US",
    "transactionRef": ["0xabc123def456..."],
    "customer": {
      "createdAt": "2025-12-01T10:00:00Z",
      "uid": "usr_x9y8z7w6v5",
      "dateOfBirth": "1990-05-15",
      "status": 2,
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+14155552671",
      "gender": 1,
      "country": "US",
      "ipAddress": "203.0.113.42",
      "remarks": "",
      "riskStatus": 1,
      "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105",
        "country": "US"
      },
      "amlData": null
    }
  },
  "message": "success",
  "traceId": "abcd1234efgh5678"
}
```

### Status Values

| Status              | Meaning                                                                     |
| ------------------- | --------------------------------------------------------------------------- |
| `unknown`           | Status not yet classified or returned by upstream systems                   |
| `created`           | Transfer order successfully created; awaiting next action                   |
| `pending`           | Awaiting required action (funding, approval, or background checks)          |
| `authorized`        | User action or crypto funding authorized; ready for next processing step    |
| `accepted`          | Transfer accepted by the system; queued for processing                      |
| `received`          | Stablecoin funds (USDC/USDT) received and validated                         |
| `rejected`          | Transfer rejected due to bank or beneficiary validation                     |
| `expired`           | Transfer order expired due to timeout (e.g., funding window passed)         |
| `canceled`          | User or partner canceled the transfer before completion                     |
| `failed`            | Transfer failed due to banking or liquidity errors                          |
| `refunded`          | Funds returned to sender after failure or rejection                         |
| `review`            | Under manual risk review                                                    |
| `processing_failed` | Internal processing error after acceptance; retry or manual action required |

<Note>
  This endpoint is ideal for dashboards, reconciliation tools, CRMs and internal audit systems.
</Note>

### Highlights:

* expiry – time window in which funding must be completed
* payment.bankTxnInfo – details of the bank-side transaction (fees, sender, receiver)
* payment.cryptoTxnInfo – details of the crypto-side transfer (hash, chain, status)
* payment.qrTxnInfo – optional QR information if a QR-based payment method is used
* payment.status – current transfer order status

## Status & Traceability

Each API response includes:

* code – internal status code
* message – human-readable description
* traceId – correlation ID for debugging and support

Use traceId when contacting Rampnow support for any specific transaction.

## Typical Integration Pattern

<Steps>
  <Step title="1. Register beneficiary">
    Call **CreateBeneficiary**, store `userUid` and `walletUid` in your database.
  </Step>

  <Step title="2. Show quote to user">
    Call **GetTransferOrderQuote**, display `srcamount`, `dstamount` and `exchangeRate`.
  </Step>

  <Step title="3. Create transfer order">
    Call **CreateTransferOrder** with the selected quote, beneficiary `walletUid` and your `apiKey`.
  </Step>

  <Step title="4. Fund with USDC/USDT">
    Send the required crypto amount to the address defined in your integration (or as part of payment instructions).
  </Step>

  <Step title="5. Monitor & reconcile">
    Use your internal logs + Rampnow responses (`traceId`, `reference`, `status`) to reconcile payouts.
  </Step>
</Steps>

<CardGroup>
  <Card title="Beneficiaries" icon="user" href="#1-create-beneficiary">
    Create and manage payout recipients.
  </Card>

  <Card title="FX Routing" icon="arrows-rotate" href="/quickstart/make-payments/FX-routing">
    Understand how conversion and pricing works.
  </Card>

  <Card title="Cross-Border Payments" icon="globe" href="/quickstart/make-payments/cross-border-payments">
    See end-to-end cross-border payout flows.
  </Card>

  <Card title="Treasury Management" icon="building-columns" href="/quickstart/make-payments/treasury-management">
    Use stablecoin funding for global treasury operations.
  </Card>
</CardGroup>