Collect a Payin

Collecting a payment from a payer follows the same three steps regardless of the rail:

Get a quote

Convert the amount you want to receive (for example, USDC) into the local currency the payer will pay in.

Generate a payin code

Create the payin and render the returned qrCode. For BRL you also get a PIX copy-and-paste code (brCode); for BOB you get a raw QR payload (qrPayload).

Poll the payin status

Check the payin status until state reaches funds_received.

The examples below use the fetch API available in Node.js 18+ and modern browsers. Authenticate each request with your API key via the api-key header.

Shared setup

const BASE_URL = "https://stablecoin-api.sandbox.getmeru.com";
const API_KEY = "<api-key>";

const headers = {
  "Content-Type": "application/json",
  "api-key": API_KEY,
};

interface Quote {
  paymentRail: string;
  fromCurrency: string;
  toCurrency: string;
  fromAmount: number;
  toAmount: number;
  rate: number;
  quotedAt: string;
  expiresAt: string;
}

interface Payin {
  success: boolean;
  paymentId: string;
  qrCode: string;
  expireAt: string;
  brCode?: string;
  qrPayload?: string;
}

interface PayinStatus {
  paymentId: string;
  isValid: boolean;
  isExpired: boolean;
  expireAt?: string;
  state?: string;
}

async function getPayinStatus(paymentId: string): Promise<PayinStatus> {
  const res = await fetch(
    `${BASE_URL}/v1/payins/qr-code/${paymentId}/status`,
    { headers },
  );
  return res.json();
}

Bolivia (QR)
Brazil (PIX)

Get a quote

Quote how much BOB the payer pays for the USDC you want to receive.

const quoteRes = await fetch(`${BASE_URL}/v1/payins/quotes`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    paymentRail: "qr_code",
    amount: 100,
    fromCurrency: "USDC",
    toCurrency: "BOB",
  }),
});

const quote: Quote = await quoteRes.json();
// quote.toAmount is the amount to charge the payer in BOB.

Generate the payin code

Use the quoted BOB amount to generate the payin. The response includes a renderable qrCode and the raw qrPayload.

const payinRes = await fetch(`${BASE_URL}/v1/payins/qr-code`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    orderId: "ORD-12346",
    amount: quote.toAmount,
    currency: "BOB",
    externalId: "EXT-10002",
  }),
});

const payin: Payin = await payinRes.json();
// Render payin.qrCode (a data URL) as an <img>, or display payin.qrPayload.
console.log(payin.paymentId, payin.qrPayload);

Poll the payin status

Poll until the payer completes the payment (state === "funds_received").

const status = await getPayinStatus(payin.paymentId);

if (status.state === "funds_received") {
  // Funds received — fulfill the order.
}

Get a quote

Quote how much BRL the payer pays for the USDC you want to receive.

const quoteRes = await fetch(`${BASE_URL}/v1/payins/quotes`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    paymentRail: "qr_code",
    amount: 100,
    fromCurrency: "USDC",
    toCurrency: "BRL",
  }),
});

const quote: Quote = await quoteRes.json();
// quote.toAmount is the amount to charge the payer in BRL.

Generate the payin code

Use the quoted BRL amount to generate the payin. The response includes a renderable qrCode and the PIX copy-and-paste code in brCode.

const payinRes = await fetch(`${BASE_URL}/v1/payins/qr-code`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    orderId: "ORD-12345",
    amount: quote.toAmount,
    currency: "BRL",
    externalId: "EXT-10001",
  }),
});

const payin: Payin = await payinRes.json();
// Render payin.qrCode (a data URL), or show payin.brCode for copy-and-paste.
console.log(payin.paymentId, payin.brCode);

Poll the payin status

Poll until the payer completes the payment (state === "funds_received").

const status = await getPayinStatus(payin.paymentId);

if (status.state === "funds_received") {
  // Funds received — fulfill the order.
}

A payin code expires after the expireAt timestamp (30 minutes by default, 24 hours maximum). Generate a new payin code if the previous one expires before the payer pays.

Generate a Payin Code

Full request and response reference for creating a payin.

Get Payin Status

Look up the validity and state of a payin.

API Documentation

Guides

Balances

Quotes

Payouts

Payins

Checkout

Cards

Webhooks

Collect a Payin

Generate a Payin Code

Get Payin Status

​Related

Generate a Payin Code

Get Payin Status

Related