On-Ramp Payments

Overview

On-ramp payments allow you to convert fiat currency into cryptocurrency.

On-Ramp Flow

The on-ramp process follows these steps:

Get Exchange Rate - Check current rates and fees
Create Quote - Lock in a rate for a specific time period
Create On-Ramp Transfer - Initiate the transfer
Send Fiat - User sends fiat via bank transfer
Receive Crypto - Crypto is deposited to the wallet

Step 1: Get Exchange Rate

Before creating a quote, check the current exchange rate and fees:

POST /payments/{userId}/rate
Content-Type: application/json
X-API-KEY: sk_dev_your_api_key

{
  "source": {
    "currency": "USD",
    "amount": 1000,
    "rail": "ACH"
  },
  "destination": {
    "currency": "USDC",
    "rail": "POLYGON",
    "countryCode": "US"
  },
  "developerVariableFee": 0.005
}

Response

{
  "sourceCurrency": "USD",
  "sourceAmount": 1000,
  "sourceRail": "ACH",
  "destinationCurrency": "USDC",
  "destinationAmount": 994.5,
  "destinationRail": "POLYGON",
  "destinationCountryCode": "US",
  "exchangeRate": 1.0,
  "fee": 5.5
}

Step 2: Create Quote

Lock in the exchange rate by creating a quote:

POST /payments/{userId}/quote
Content-Type: application/json
X-API-KEY: sk_dev_your_api_key

{
  "source": {
    "currency": "USD",
    "amount": 1000,
    "rail": "ACH"
  },
  "destination": {
    "currency": "USDC",
    "rail": "POLYGON",
    "countryCode": "US",
    "paymentAccountId": "wallet_id_here"
  },
  "developerVariableFee": 0.005
}

Response

{
  "id": "quote_123456",
  "sourceCurrency": "USD",
  "sourceAmount": 1000,
  "sourceRail": "ACH",
  "destinationCurrency": "USDC",
  "destinationAmount": 994.5,
  "destinationRail": "POLYGON",
  "destinationCountryCode": "US",
  "exchangeRate": 1.0,
  "totalFee": 5.5,
  "expiresAt": "2024-01-15T10:45:00Z",
  "createdAt": "2024-01-15T10:30:00Z"
}

Step 3: Create On-Ramp Transfer

Initiate the on-ramp transfer using your quote:

POST /payments/recipient/{recipientId}/on-ramp
Content-Type: application/json
X-API-KEY: sk_dev_your_api_key

{
  "idempotencyKey": "unique-transfer-id-67890",
  "quoteId": "quote_123456",
  "walletId": "wallet_id_here",
  "fromAccountNumber": "123456789",
  "paymentReason": "TRANSFER_TO_SELF",
  "documentReference": "Purchase-2024-001",
  "files": [
    "data:application/pdf;name=..."
  ]
}

Response

{
  "id": "txn_456789",
  "idempotencyKey": "unique-transfer-id-67890",
  "type": "ON_RAMP",
  "status": "AWAITING_FUNDS",
  "quoteId": "quote_123456",
  "bankAccountId": null,
  "walletId": "wallet_id_here",
  "transactionHash": null,
  "fee": 5.5,
  "depositInstructions": {
    "bankName": "Partner Bank",
    "accountNumber": "9876543210",
    "routingNumber": "021000021",
    "reference": "REF123456",
    "amount": 1000,
    "currency": "USD"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "expiresAt": "2024-01-15T11:30:00Z"
}

Step 4: User Sends Fiat

The user sends fiat currency to the provided bank account using the deposit instructions from the transfer response.

Important: The user must include the reference number in their bank transfer. This is how the system identifies which on-ramp transfer the payment is for.

Step 5: Receive Crypto

After fiat funds are received, crypto funds are sent to the destination wallet and the transfer completes.

Monitoring Transfers

Get Transfer Status

GET /payments/{id}
X-API-KEY: sk_dev_your_api_key

Example Status Updates

{
  "id": "txn_456789",
  "status": "AWAITING_FUNDS",
  "createdAt": "2024-01-15T10:30:00Z"
}

After receiving fiat:

{
  "id": "txn_456789",
  "status": "PROCESSING",
  "sentAt": "2024-01-15T11:00:00Z"
}

After sending crypto:

{
  "id": "txn_456789",
  "status": "COMPLETED",
  "transactionHash": "0xabc123...",
  "completedAt": "2024-01-15T11:10:00Z"
}

Webhooks

Set up webhooks to receive real-time updates:

POST /webhooks
Content-Type: application/json
X-API-KEY: sk_dev_your_api_key

{
  "url": "https://your-app.com/webhooks/sentra",
  "secret": "your_webhook_secret",
  "events": ["payment.updated"]
}

Webhook Payload Example

{
  "event": "payment.updated",
  "data": {
    "id": "txn_456789",
    "status": "COMPLETED",
    "type": "ON_RAMP",
    "transactionHash": "0xabc123...",
    "completedAt": "2024-01-15T11:10:00Z"
  },
  "timestamp": "2024-01-15T11:10:05Z"
}

Transaction Statuses

Status	Description
`AWAITING_FUNDS`	Waiting for fiat to be received
`PENDING`	Fiat received, being verified
`PROCESSING`	Converting fiat to crypto
`SENT`	Crypto sent to wallet
`COMPLETED`	Successfully completed
`FAILED`	Transaction failed
`EXPIRED`	Transfer expired
`REFUNDED`	Funds returned to sender

On-Ramp Payments

On this page