Payout API

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.

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

High-Level Flow

Create Beneficiary

Use CreateBeneficiary to register the receiver with their KYC profile and bank account details. Response returns userUid and walletUid.

(Optional) Retrieve Beneficiary

Use GetBeneficiary to check status, attached wallets, and bank account details.

Get Transfer Quote

Use GetTransferOrderQuote to preview FX, source amount and destination amount for a given corridor and currency pair.

Create Transfer Order

Use CreateTransferOrder to initiate the payout using the walletUid from the beneficiary and your source/destination currency setup. Response includes payment instructions (bank or crypto), status, and expiry.

Get Transfer Status (Using traceId)

Use Get Transfer Status to retrieve the latest status of any payout using the traceId returned by all Rampnow endpoints (CreateTransferOrder, webhooks, and error responses).

1. Create Beneficiary

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

Request

POST https://api.dev.rampnow.io/api/partner/v1/ext/customer_user/beneficiary

Request body

{
  "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",
    "dateOfBirth": "<string>",
    "email": "<string>",
    "firstName": "<string>",
    "gender": "unknown",
    "lastName": "<string>",
    "phone": "<string>"
  }
}

Key concepts:

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

Response

{
  "code": 123,
  "data": {
    "userUid": "<string>",
    "walletUid": "<string>"
  },
  "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

GET https://api.dev.rampnow.io/api/partner/v1/ext/customer_user/beneficiary/{uid}

Path parameter:

uid – the userUid returned from CreateBeneficiary

Response

{
  "code": 123,
  "data": {
    "address": {
      "city": "<string>",
      "country": "AD",
      "line1": "<string>",
      "line2": "<string>",
      "postalCode": "<string>",
      "state": "<string>",
      "subDivision": "<string>"
    },
    "country": "AD",
    "dateOfBirth": "<string>",
    "email": "<string>",
    "firstName": "<string>",
    "gender": "unknown",
    "lastName": "<string>",
    "phone": "<string>",
    "status": "unknown",
    "uid": "<string>",
    "wallets": [
      {
        "bankAccountDetail": {
          "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>"
        },
        "cryptoAccountDetail": {
          "address": "<string>",
          "custodyType": "unknown",
          "externalAddress": "<string>",
          "uid": "<string>"
        }
      }
    ]
  },
  "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.

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

Request

GET https://api.dev.rampnow.io/api/partner/v1/ext/transfer_order/quote

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

Response

{
  "code": 123,
  "data": {
    "dstamount": "<string>",
    "dstchain": "abstract",
    "dstcurrency": "AAAFISH",
    "exchangeRate": "<string>",
    "srcamount": "<string>",
    "srcchain": "abstract",
    "srccurrency": "AAAFISH"
  },
  "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.

Request

POST https://api.dev.rampnow.io/api/partner/v1/ext/transfer_order

Request Body

{
  "apiKey": "<string>",
  "dstAmount": "<string>",
  "dstChain": "abstract",
  "dstCurrency": "AAAFISH",
  "orderType": "unknown",
  "reference": "<string>",
  "srcChain": "abstract",
  "srcCurrency": "AAAFISH",
  "walletUid": "<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

Response

{
  "code": 123,
  "data": {
    "amount": "<string>",
    "currency": "AAAFISH",
    "expiry": 123,
    "payment": {
      "bankTxnInfo": {
        "fee": "<string>",
        "message": "<string>",
        "receiver": {
          "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>"
        },
        "sender": {
          "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>"
        }
      },
      "cryptoTxnInfo": {
        "amount": "<string>",
        "chain": "abstract",
        "currency": "AAAFISH",
        "fillAmount": "<string>",
        "receiverAddress": "<string>",
        "senderAddress": "<string>",
        "status": "<string>",
        "transactionHash": "<string>"
      },
      "notes": [
        {
          "note": "<string>"
        }
      ],
      "qrTxnInfo": {
        "image": "<string>",
        "imageUrl": "<string>",
        "payload": "<string>",
        "referenceUid": "<string>"
      },
      "redirectUrl": "<string>",
      "status": "unknown"
    }
  },
  "message": "<string>",
  "traceId": "<string>"
}

5. Get Transfer Status (Using `traceId`)

You can retrieve the latest status of any payout using the traceId 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.

traceId is globally unique and can be used to trace a payout through support, logs, and audit flows.

Endpoint

Request

GET /api/partner/v1/ext/transfer_order/status?traceId={traceId}

Respose

{
  "code": 0,
  "message": "success",
  "traceId": "abcd1234efgh5678",
  "data": {
    "transferOrderId": "to_0011223344",
    "reference": "merchant_2025_00321",
    "status": "completed",
    "funding": {
      "currency": "USDC",
      "amount": "123.45",
      "transactionHash": "0xabc123...",
      "chain": "arbitrum-one",
      "confirmed": true
    },
    "fx": {
      "srcCurrency": "USDC",
      "dstCurrency": "INR",
      "srcAmount": "123.45",
      "dstAmount": "10230.00",
      "exchangeRate": "82.88",
      "timestamp": "2025-02-02T12:43:11Z"
    },
    "payout": {
      "rail": "IMPS",
      "bankReferenceId": "IMPS20394823",
      "beneficiary": {
        "name": "John Doe",
        "country": "IN"
      },
      "status": "completed",
      "completedAt": "2025-02-02T12:45:03Z"
    }
  }
}

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, compliance, 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 compliance or risk review
`processing_failed`	Internal processing error after acceptance; retry or manual action required

This endpoint is ideal for dashboards, reconciliation tools, CRMs, and internal audit systems.

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

1. Register beneficiary

Call CreateBeneficiary, store userUid and walletUid in your database.

2. Show quote to user

Call GetTransferOrderQuote, display srcamount, dstamount, and exchangeRate.

3. Create transfer order

Call CreateTransferOrder with the selected quote, beneficiary walletUid, and your apiKey.

4. Fund with USDC/USDT

Send the required crypto amount to the address defined in your integration (or as part of payment instructions).

5. Monitor & reconcile

Use your internal logs + Rampnow responses (traceId, reference, status) to reconcile payouts.

Beneficiaries

Create and manage payout recipients.

FX Routing

Understand how conversion and pricing works.

Cross-Border Payments

See end-to-end cross-border payout flows.

Treasury Management

Use stablecoin funding for global treasury operations.

Learn about Rampnow

Resources

Onramp

Offramp

Make Payments

Customers and Compliance

policies

High-Level Flow

1. Create Beneficiary

Key concepts:

2. Get Beneficiary

Path parameter:

3. Get Transfer Order Quote

Fields:

4. Create Transfer Order

Key fields:

5. Get Transfer Status (Using `traceId`)

Endpoint

Status Values

Highlights:

Status & Traceability

Typical Integration Pattern

Beneficiaries

FX Routing

Cross-Border Payments

Treasury Management

Learn about Rampnow

Resources

Onramp

Offramp

Make Payments

Customers and Compliance

policies

​High-Level Flow

​1. Create Beneficiary

​Key concepts:

​2. Get Beneficiary

​Path parameter:

​3. Get Transfer Order Quote

​Fields:

​4. Create Transfer Order

​Key fields:

​5. Get Transfer Status (Using traceId)

​Endpoint

​Status Values

​Highlights:

​Status & Traceability

​Typical Integration Pattern

Beneficiaries

FX Routing

Cross-Border Payments

Treasury Management

High-Level Flow

1. Create Beneficiary

Key concepts:

2. Get Beneficiary

Path parameter:

3. Get Transfer Order Quote

Fields:

4. Create Transfer Order

Key fields:

5. Get Transfer Status (Using `traceId`)

Endpoint

Status Values

Highlights:

Status & Traceability

Typical Integration Pattern