Payout API - partner-service

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 Remitter

Use CreateRemitter to register the sender with their KYC profile and KYC details. Response returns userUid.

(Optional) Retrieve Remitter

Use GetRemitter to check KYC status of the remitter being added.

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, remitterUid from remitter and your source/destination currency setup. Response includes payment instructions (bank or crypto), status, partner fee breakdown and expiry.

Get Transfer Order Status

Use GetTransferOrder API to retrieve the latest status of any transfer using the Transfer Order ID returned by CreateTransferOrder API.

1. Create Remitter

Create a Remitter (sender) with user KYC data.

Request

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

Request body

{
  "user": {
    "email": "[email protected]",
    "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 (KYC for the remitter)
idDocs – optional document set for enhanced checks (front/back URLs, etc.)

Response

{
  "code": 123,
  "data": {
    "uid": "usr_x9y8z7w6v5",
    "type": 0,
    "name": "John Doe",
    "email": "[email protected]",
    "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

GET https://api.sandbox.rampnow.io/api/partner/v1/ext/transfer_order/remitter/{uid}

Path parameter:

uid – the uid returned from CreateRemitter

Response

{
  "code": 123,
  "data": {
    "uid": "usr_x9y8z7w6v5",
    "type": 0,
    "name": "John Doe",
    "email": "[email protected]",
    "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 KYC data and one linked bank account.

Request

POST https://api.sandbox.rampnow.io/api/partner/v1/ext/transfer_order/beneficiary/wallet

Request body

{
  "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 (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": {
    "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": "[email protected]",
        "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

GET https://api.sandbox.rampnow.io/api/partner/v1/ext/transfer_order/beneficiary/wallet/{uid}

Path parameter:

uid – the userUid returned from CreateBeneficiary

Response

{
  "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": "[email protected]",
        "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.

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.sandbox.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": {
    "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.

Request

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

Request Body

{
  "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

Response

{
  "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.

uid 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/:uid

Response

{
  "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": "[email protected]",
      "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, 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.

Documentation Index

​High-Level Flow

​1. Create Remitter

​Key concepts:

​2. Get Remitter

​Path parameter:

​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 uid)

​Endpoint

​Status Values

​Highlights:

​Status & Traceability

​Typical Integration Pattern

Beneficiaries

FX Routing

Cross-Border Payments

Treasury Management

High-Level Flow

1. Create Remitter

Key concepts:

2. Get Remitter

Path parameter:

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 `uid`)

Endpoint

Status Values

Highlights:

Status & Traceability

Typical Integration Pattern